pymel.core.general.rename

rename(obj, newname, **kwargs)

Renames the given object to have the new name. If only one argument is supplied the command will rename the (first) selected object. If the new name conflicts with an existing name, the object will be given a unique name based on the supplied name. It is not legal to rename an object to the empty string. When a transform is renamed then any shape nodes beneath the transform that have the same prefix as the old transform name are renamed. For example, rename nurbsSphere1 ballwould rename nurbsSphere1|nurbsSphereShape1to ball|ballShape. If the new name ends in a single ‘#’ then the rename command will replace the trailing ‘#’ with a number that ensures the new name is unique.

Modifications:
  • if the full path to an object is passed as the new name, the shortname of the object will automatically be used

Flags:

Long Name / Short Name Argument Types Properties
ignoreShape / ignoreShape bool ../../../_images/create.gif
  Indicates that renaming of shape nodes below transform nodes should be prevented.
uuid / uid bool ../../../_images/create.gif
  Indicates that the new name is actually a UUID, and that the command should change the node’s UUID. (In which case its name remains unchanged.) Flag can have multiple arguments, passed either as a tuple or a list.

Derived from mel command maya.cmds.rename

Example:

import pymel.core as pm

# create two namespaces under the root namespace and create
# a sphere under the root namespace and a sphere under one
# of the new namespaces.
pm.namespace( set=':' )
# Result: u'' #
pm.sphere( n='sphere1' )
# Result: [nt.Transform(u'sphere1'), nt.MakeNurbSphere(u'makeNurbSphere1')] #
pm.namespace( add='nsA' )
# Result: u'nsA' #
pm.namespace( add='nsB' )
# Result: u'nsB' #
pm.namespace( set='nsA' )
# Result: u'nsA' #
pm.sphere( n='sphere2' )
# Result: [nt.Transform(u'nsA:sphere2'), nt.MakeNurbSphere(u'nsA:makeNurbSphere1')] #
pm.namespace( set=':' )
# Result: u'' #
# change name of sphere1
pm.rename('sphere1', 'spinning_ball')
# Result: nt.Transform(u'spinning_ball') #

# change name of spinning_ball back to sphere1
pm.select( 'spinning_ball', r=True )
pm.rename( 'sphere1' )

# move sphere2 to namespace nsB
pm.rename( 'nsA:sphere2', 'nsB:sphere2' )
nsB:sphere2

# move sphere2 back to namespace nsA when not in the root namespace
# Note the ":" appearing in front of the new name to indicate
# we want to move the object to namespace nsA under the root namespace.
pm.namespace( set='nsB' )
pm.rename( 'nsB:sphere2', ':nsA:sphere2' )
nsA:sphere2

# Let's try this without the leading ":" in the new name.
# Since we are namespace nsA, in affect, what we are trying to do
# is rename :nsB:sphere2 to :nsA:nsB:sphere3. Since there isn't a
# nsB namespace under the namespace nsA, the namespace specification
# on new name is ignored and a warning is issued.
pm.namespace( set=':nsA' )
pm.rename( 'nsA:sphere2', 'nsB:sphere3' )
# Warning: Removing invalid characters from name. #
nsA:sphere3

# rename an object when not in the root namespace
# and move the object to current namespace
pm.namespace( set=':nsB' )
pm.rename( 'nsA:sphere3', 'sphere4' )
nsB:sphere4

# rename an object with an absolute name to move it into a new namespace.
# The namespace does not exist so will be created.
pm.namespace( set=':nsB' )
pm.rename( 'nsA:sphere3', ':nsC:sphere4' )
nsC:sphere4