pymel.core.general.PyNode

Inheritance diagram of PyNode

class PyNode(*args, **kwargs)

Abstract class that is base for all pymel nodes classes.

The names of nodes and attributes can be passed to this class, and the appropriate subclass will be determined.

>>> PyNode('persp')
nt.Transform(u'persp')
>>> PyNode('persp.tx')
Attribute(u'persp.translateX')

If the passed node or attribute does not exist an error will be raised.

addPrefix(prefix)

Returns the object’s name with a prefix added to the beginning of the name

Return type:other.NameParser
connections(*args, **kwargs)

This command returns a list of all attributes/objects of a specified type that are connected to the given object(s). If no objects are specified then the command lists the connections on selected nodes.

Modifications:
  • returns an empty list when the result is None

  • returns an empty list (with a warning) when the arg is an empty list, tuple,

    set, or frozenset, making it’s behavior consistent with when None is passed, or no args and nothing is selected (would formerly raise a TypeError)

  • When ‘connections’ flag is True, the attribute pairs are returned in a 2D-array:

    [['checker1.outColor', 'lambert1.color'], ['checker1.color1', 'fractal1.outColor']]
    
  • added sourceFirst keyword arg. when sourceFirst is true and connections is also true,

    the paired list of plugs is returned in (source,destination) order instead of (thisnode,othernode) order. this puts the pairs in the order that disconnectAttr and connectAttr expect.

  • added ability to pass a list of types

    rtype:PyNode list
Flags:
Long name (short name) Argument Types Properties
connections (c) bool ../../../_images/create.gif
 
If true, return both attributes involved in the connection. The one on the specified object is given first. Default false.
destination (d) bool ../../../_images/create.gif
 
Give the attributes/objects that are on the “destination” side of connection to the given object. Default true.
exactType (et) bool ../../../_images/create.gif
 
When set to true, -t/type only considers node of this exact type. Otherwise, derived types are also taken into account.
plugs (p) bool ../../../_images/create.gif
 
If true, return the connected attribute names; if false, return the connected object names only. Default false;
shapes (sh) bool ../../../_images/create.gif
 
Actually return the shape name instead of the transform when the shape is “selected”. Default false.
skipConversionNodes (scn) bool ../../../_images/create.gif
 

If true, skip over unit conversion nodes and return the node connected to the conversion node on the other side. Default false.Flag can appear in Create mode of commandFlag can have multiple arguments, passed either as a tuple or a list.

source (s) bool ../../../_images/create.gif
 
Give the attributes/objects that are on the “source” side of connection to the given object. Default true.
type (t) unicode ../../../_images/create.gif
 
If specified, only take objects of a specified type.

Derived from mel command maya.cmds.listConnections

Example:

import pymel.core as pm

pm.sphere( ch=True, n='BALL' )
# Result: [nt.Transform(u'BALL'), nt.MakeNurbSphere(u'makeNurbSphere1')] #
pm.setKeyframe()
# Result: 10 #
# List all connections to BALL
list = pm.listConnections('BALL')
# List only incoming connections from BALL.tx
pm.listConnections( 'BALL.tx', d=False, s=True )
# Result: [nt.AnimCurveTL(u'BALL_translateX')] #
# List connections from BALL to nodes of type 'transform'
pm.listConnections( t='transform' )
# Result: [] #
# List connections on BALL, ignoring unit conversion nodes
pm.listConnections( 'BALL', scn=True )
# Result: [nt.AnimCurveTU(u'BALL_visibility'), nt.AnimCurveTL(u'BALL_translateX'), nt.AnimCurveTL(u'BALL_translateY'), nt.AnimCurveTL(u'BALL_translateZ'), nt.AnimCurveTA(u'BALL_rotateX'), nt.AnimCurveTA(u'BALL_rotateY'), nt.AnimCurveTA(u'BALL_rotateZ'), nt.AnimCurveTU(u'BALL_scaleX'), nt.AnimCurveTU(u'BALL_scaleY'), nt.AnimCurveTU(u'BALL_scaleZ')] #
deselect()
exists(**kwargs)

objExists

future(*args, **kwargs)

Modifications: - returns an empty list when the result is None - added a much needed ‘type’ filter - added an ‘exactType’ filter (if both ‘exactType’ and ‘type’ are present, ‘type’ is ignored)

rtype:DependNode list
history(*args, **kwargs)

This command traverses backwards or forwards in the graph from the specified node and returns all of the nodes whose construction history it passes through. The construction history consists of connections to specific attributes of a node defined as the creators and results of the node’s main data, eg. the curve for a Nurbs Curve node. For information on history connections through specific plugs use the “listConnections” command first to find where the history begins then use this command on the resulting node.

Modifications:
  • returns an empty list when the result is None

  • raises a RuntimeError when the arg is an empty list, tuple, set, or

    frozenset, making it’s behavior consistent with when None is passed, or no args and nothing is selected (would formerly raise a TypeError)

  • added a much needed ‘type’ filter

  • added an ‘exactType’ filter (if both ‘exactType’ and ‘type’ are present, ‘type’ is ignored)

    rtype:DependNode list
Flags:
Long name (short name) Argument Types Properties
allConnections (ac) bool ../../../_images/create.gif
 

If specified, the traversal that searches for the history or future will not restrict its traversal across nodes to only dependent plugs. Thus it will reach all upstream nodes (or all downstream nodes for f/future).

allFuture (af) bool ../../../_images/create.gif
 

If listing the future, list all of it. Otherwise if a shape has an attribute that represents its output geometry data, and that plug is connected, only list the future history downstream from that connection.

allGraphs (ag) bool ../../../_images/create.gif
 
By default, the traversal will remain in the current graph. If this flag is set to true, the traversal will descend into subgraphs, and ascend into parent graphs.
breadthFirst (bf) bool ../../../_images/create.gif
 

The breadth first traversal will return the closest nodes in the traversal first. The depth first traversal will follow a complete path away from the node, then return to any other paths from the node. Default is depth first.

future (f) bool ../../../_images/create.gif
 
List the future instead of the history.
futureLocalAttr (fl) bool ../../../_images/query.gif
 

This flag allows querying of the local-space future-related attribute(s) on shape nodes.Flag can appear in Create mode of commandFlag can have multiple arguments, passed either as a tuple or a list.

futureWorldAttr (fw) bool ../../../_images/query.gif
 
This flag allows querying of the world-space future-related attribute(s) on shape nodes.
groupLevels (gl) bool ../../../_images/create.gif
 
The node names are grouped depending on the level. 1 is the lead, the rest are grouped with it.
historyAttr (ha) bool ../../../_images/query.gif
 
This flag allows querying of the attribute where history connects on shape nodes.
interestLevel (il) int ../../../_images/create.gif
 

If this flag is set, only nodes whose historicallyInteresting attribute value is not less than the value will be listed. The historicallyInteresting attribute is 0 on nodes which are not of interest to non-programmers. 1 for the TDs, 2 for the users.

leaf (lf) bool ../../../_images/create.gif
 
If transform is selected, show history for its leaf shape. Default is true.
levels (lv) int ../../../_images/create.gif
 
Levels deep to traverse. Setting the number of levels to 0 means do all levels. All levels is the default.
pruneDagObjects (pdo) bool ../../../_images/create.gif
 
If this flag is set, prune at dag objects.

Derived from mel command maya.cmds.listHistory

Example:

import pymel.core as pm

pm.curve( d=3, p=[(-3, 0, 0),(-1, 0, 6),(6, 0, 8),(8, 0, 2)], k=[0,0,0,1,1,1], n="snake" )
# Result: nt.Transform(u'snake') #
pm.instance( n="rattler" )
# Result: [nt.Transform(u'rattler')] #
pm.revolve( 'rattler', ch=True, n="charmer" )
# Result: [nt.Transform(u'charmer'), nt.Revolve(u'revolve1')] #
pm.revolve( 'snake', ch=True, n="medusa" )
# Result: [nt.Transform(u'medusa'), nt.Revolve(u'revolve2')] #

pm.listHistory()
# Result: [nt.NurbsSurface(u'medusaShape'), nt.Revolve(u'revolve2'), nt.NurbsCurve(u'snake|snakeShape')] #

pm.listHistory( 'charmer' )
# Result: [nt.NurbsSurface(u'charmerShape'), nt.Revolve(u'revolve1'), nt.NurbsCurve(u'rattler|snakeShape')] #

pm.listHistory( 'medusa', lv=1 )
# Result: [nt.NurbsSurface(u'medusaShape'), nt.Revolve(u'revolve2')] #

pm.listHistory( 'medusa', future=True )
# Result: [nt.NurbsSurface(u'medusaShape'), nt.ShadingEngine(u'initialShadingGroup')] #

# If you just list the curve's future you get both directions
pm.listHistory( 'curveShape1', future=True )
[u'snake|curveShape1', u'revolve2', u'medusaShape', u'revolve1', u'charmerShape']

# To follow only one history you'll need to follow the path you
# want first, then add the node you started at if so desired since
# it will not be included (here snake|curveShape1 won't list).

# List the future of the first curve
hist = pm.listConnections('curveShape1.ws[0]',c=1)
pm.listHistory( hist[1], future=True )
[u'revolve2', u'medusaShape']

# List the future of the second curve
hist = pm.listConnections('curveShape1.ws[1]',c=1)
pm.listHistory( hist[1], future=True )
[u'revolve1', u'charmerShape']

pm.listHistory( leaf=0 )
[u'medusa']
listConnections(*args, **kwargs)

This command returns a list of all attributes/objects of a specified type that are connected to the given object(s). If no objects are specified then the command lists the connections on selected nodes.

Modifications:
  • returns an empty list when the result is None

  • returns an empty list (with a warning) when the arg is an empty list, tuple,

    set, or frozenset, making it’s behavior consistent with when None is passed, or no args and nothing is selected (would formerly raise a TypeError)

  • When ‘connections’ flag is True, the attribute pairs are returned in a 2D-array:

    [['checker1.outColor', 'lambert1.color'], ['checker1.color1', 'fractal1.outColor']]
    
  • added sourceFirst keyword arg. when sourceFirst is true and connections is also true,

    the paired list of plugs is returned in (source,destination) order instead of (thisnode,othernode) order. this puts the pairs in the order that disconnectAttr and connectAttr expect.

  • added ability to pass a list of types

    rtype:PyNode list
Flags:
Long name (short name) Argument Types Properties
connections (c) bool ../../../_images/create.gif
 
If true, return both attributes involved in the connection. The one on the specified object is given first. Default false.
destination (d) bool ../../../_images/create.gif
 
Give the attributes/objects that are on the “destination” side of connection to the given object. Default true.
exactType (et) bool ../../../_images/create.gif
 
When set to true, -t/type only considers node of this exact type. Otherwise, derived types are also taken into account.
plugs (p) bool ../../../_images/create.gif
 
If true, return the connected attribute names; if false, return the connected object names only. Default false;
shapes (sh) bool ../../../_images/create.gif
 
Actually return the shape name instead of the transform when the shape is “selected”. Default false.
skipConversionNodes (scn) bool ../../../_images/create.gif
 

If true, skip over unit conversion nodes and return the node connected to the conversion node on the other side. Default false.Flag can appear in Create mode of commandFlag can have multiple arguments, passed either as a tuple or a list.

source (s) bool ../../../_images/create.gif
 
Give the attributes/objects that are on the “source” side of connection to the given object. Default true.
type (t) unicode ../../../_images/create.gif
 
If specified, only take objects of a specified type.

Derived from mel command maya.cmds.listConnections

Example:

import pymel.core as pm

pm.sphere( ch=True, n='BALL' )
# Result: [nt.Transform(u'BALL'), nt.MakeNurbSphere(u'makeNurbSphere1')] #
pm.setKeyframe()
# Result: 10 #
# List all connections to BALL
list = pm.listConnections('BALL')
# List only incoming connections from BALL.tx
pm.listConnections( 'BALL.tx', d=False, s=True )
# Result: [nt.AnimCurveTL(u'BALL_translateX')] #
# List connections from BALL to nodes of type 'transform'
pm.listConnections( t='transform' )
# Result: [] #
# List connections on BALL, ignoring unit conversion nodes
pm.listConnections( 'BALL', scn=True )
# Result: [nt.AnimCurveTU(u'BALL_visibility'), nt.AnimCurveTL(u'BALL_translateX'), nt.AnimCurveTL(u'BALL_translateY'), nt.AnimCurveTL(u'BALL_translateZ'), nt.AnimCurveTA(u'BALL_rotateX'), nt.AnimCurveTA(u'BALL_rotateY'), nt.AnimCurveTA(u'BALL_rotateZ'), nt.AnimCurveTU(u'BALL_scaleX'), nt.AnimCurveTU(u'BALL_scaleY'), nt.AnimCurveTU(u'BALL_scaleZ')] #
listFuture(*args, **kwargs)

Modifications: - returns an empty list when the result is None - added a much needed ‘type’ filter - added an ‘exactType’ filter (if both ‘exactType’ and ‘type’ are present, ‘type’ is ignored)

rtype:DependNode list
listHistory(*args, **kwargs)

This command traverses backwards or forwards in the graph from the specified node and returns all of the nodes whose construction history it passes through. The construction history consists of connections to specific attributes of a node defined as the creators and results of the node’s main data, eg. the curve for a Nurbs Curve node. For information on history connections through specific plugs use the “listConnections” command first to find where the history begins then use this command on the resulting node.

Modifications:
  • returns an empty list when the result is None

  • raises a RuntimeError when the arg is an empty list, tuple, set, or

    frozenset, making it’s behavior consistent with when None is passed, or no args and nothing is selected (would formerly raise a TypeError)

  • added a much needed ‘type’ filter

  • added an ‘exactType’ filter (if both ‘exactType’ and ‘type’ are present, ‘type’ is ignored)

    rtype:DependNode list
Flags:
Long name (short name) Argument Types Properties
allConnections (ac) bool ../../../_images/create.gif
 

If specified, the traversal that searches for the history or future will not restrict its traversal across nodes to only dependent plugs. Thus it will reach all upstream nodes (or all downstream nodes for f/future).

allFuture (af) bool ../../../_images/create.gif
 

If listing the future, list all of it. Otherwise if a shape has an attribute that represents its output geometry data, and that plug is connected, only list the future history downstream from that connection.

allGraphs (ag) bool ../../../_images/create.gif
 
By default, the traversal will remain in the current graph. If this flag is set to true, the traversal will descend into subgraphs, and ascend into parent graphs.
breadthFirst (bf) bool ../../../_images/create.gif
 

The breadth first traversal will return the closest nodes in the traversal first. The depth first traversal will follow a complete path away from the node, then return to any other paths from the node. Default is depth first.

future (f) bool ../../../_images/create.gif
 
List the future instead of the history.
futureLocalAttr (fl) bool ../../../_images/query.gif
 

This flag allows querying of the local-space future-related attribute(s) on shape nodes.Flag can appear in Create mode of commandFlag can have multiple arguments, passed either as a tuple or a list.

futureWorldAttr (fw) bool ../../../_images/query.gif
 
This flag allows querying of the world-space future-related attribute(s) on shape nodes.
groupLevels (gl) bool ../../../_images/create.gif
 
The node names are grouped depending on the level. 1 is the lead, the rest are grouped with it.
historyAttr (ha) bool ../../../_images/query.gif
 
This flag allows querying of the attribute where history connects on shape nodes.
interestLevel (il) int ../../../_images/create.gif
 

If this flag is set, only nodes whose historicallyInteresting attribute value is not less than the value will be listed. The historicallyInteresting attribute is 0 on nodes which are not of interest to non-programmers. 1 for the TDs, 2 for the users.

leaf (lf) bool ../../../_images/create.gif
 
If transform is selected, show history for its leaf shape. Default is true.
levels (lv) int ../../../_images/create.gif
 
Levels deep to traverse. Setting the number of levels to 0 means do all levels. All levels is the default.
pruneDagObjects (pdo) bool ../../../_images/create.gif
 
If this flag is set, prune at dag objects.

Derived from mel command maya.cmds.listHistory

Example:

import pymel.core as pm

pm.curve( d=3, p=[(-3, 0, 0),(-1, 0, 6),(6, 0, 8),(8, 0, 2)], k=[0,0,0,1,1,1], n="snake" )
# Result: nt.Transform(u'snake') #
pm.instance( n="rattler" )
# Result: [nt.Transform(u'rattler')] #
pm.revolve( 'rattler', ch=True, n="charmer" )
# Result: [nt.Transform(u'charmer'), nt.Revolve(u'revolve1')] #
pm.revolve( 'snake', ch=True, n="medusa" )
# Result: [nt.Transform(u'medusa'), nt.Revolve(u'revolve2')] #

pm.listHistory()
# Result: [nt.NurbsSurface(u'medusaShape'), nt.Revolve(u'revolve2'), nt.NurbsCurve(u'snake|snakeShape')] #

pm.listHistory( 'charmer' )
# Result: [nt.NurbsSurface(u'charmerShape'), nt.Revolve(u'revolve1'), nt.NurbsCurve(u'rattler|snakeShape')] #

pm.listHistory( 'medusa', lv=1 )
# Result: [nt.NurbsSurface(u'medusaShape'), nt.Revolve(u'revolve2')] #

pm.listHistory( 'medusa', future=True )
# Result: [nt.NurbsSurface(u'medusaShape'), nt.ShadingEngine(u'initialShadingGroup')] #

# If you just list the curve's future you get both directions
pm.listHistory( 'curveShape1', future=True )
[u'snake|curveShape1', u'revolve2', u'medusaShape', u'revolve1', u'charmerShape']

# To follow only one history you'll need to follow the path you
# want first, then add the node you started at if so desired since
# it will not be included (here snake|curveShape1 won't list).

# List the future of the first curve
hist = pm.listConnections('curveShape1.ws[0]',c=1)
pm.listHistory( hist[1], future=True )
[u'revolve2', u'medusaShape']

# List the future of the second curve
hist = pm.listConnections('curveShape1.ws[1]',c=1)
pm.listHistory( hist[1], future=True )
[u'revolve1', u'charmerShape']

pm.listHistory( leaf=0 )
[u'medusa']
listSets(*args, **kwargs)

Returns list of sets this object belongs

listSets -o $this

Return type:‘PyNode’ list
namespace(root=False)

Returns the namespace of the object with trailing colon included.

See DependNode.parentNamespace for a variant which does not include the trailing colon.

By default, if the object is in the root namespace, an empty string is returned; if root is True, ‘:’ is returned in this case.

Return type:unicode
namespaceList()

Useful for cascading references. Returns all of the namespaces of the calling object as a list

Return type:unicode list
nodeType(*args, **kwargs)
objExists(**kwargs)
select(**kwargs)
stripNamespace(*args, **kwargs)

Returns the object’s name with its namespace removed. The calling instance is unaffected. The optional levels keyword specifies how many levels of cascading namespaces to strip, starting with the topmost (leftmost). The default is 0 which will remove all namespaces.

Return type:other.NameParser
swapNamespace(prefix)

Returns the object’s name with its current namespace replaced with the provided one. The calling instance is unaffected.

Return type:other.NameParser

Previous topic

pymel.core.general.ProxySlice

Next topic

pymel.core.general.Scene

Core

Core Modules

Other Modules

This Page