pymel.core.system.referenceQuery

referenceQuery(*args, **kwargs)

Use this command to find out information about references and referenced nodes. A valid target is either a reference node, a reference file, or a referenced node. Some flags don’t require a target, see flag descriptions for more information on what effect this has. When a scene contains multiple levels of file references, those edits which affect a nested reference may be stored on several different reference nodes. For example: A.ma has a reference to B.ma which has a reference to C.ma which contains a poly sphere (pSphere1). If you were to open B.ma and translate the sphere, an edit would be stored on CRN which refers to a node named “C:pSphere1”. If you were then to open A.ma and parent the sphere, an edit would be stored on BRN which refers to a node named “B:C:pSphere1”. It is important to note that when querying edits which affect a nested reference, the edits will be returned in the same format that they were applied. In the above example, opening A.ma and querying all edits which affect C.ma, would return two edits a parent edit affecting “B:C:pSphere1”, and a setAttr edit affecting “C:pSphere1”. Since there is currently no node named C:pSphere1 (only B:C:pSphere1) care will have to be taken when interpreting the returned information. The same care should be taken when referenced DAG nodes have been parented or instanced. Continuing with the previous example, let’s say that you were to open A.ma and, instead of simply parenting pSphere1, you were to instance it. While A.ma is open, “B:C:pSphere1” may now be an amibiguous name, replaced by “|B:C:pSphere1” and “group1|B:C:pSphere1”. However querying the edits which affect C.ma would still return a setAttr edit affecting “C:pSphere1” since it was applied prior to B:C:pSphere1 being instanced. Some tips: 1. Use the ‘-topReference’ flag to query only those edits which were applied from the currently open file. 2. Use the ‘-onReferenceNode’ flag to limit the results to those edits where are stored on a given reference node. You can then use various string manipulation techniques to extrapolate the current name of any affected nodes.

Modifications:

• When queried for ‘es/editStrings’, returned a list of ReferenceEdit objects
• By default, removes all edits. If neither of successfulEdits or failedEdits is given, they both default to True. If only one is given, the other defaults to the opposite value.

Flags:

Long name (short name)		Argument Types	Properties
child (ch)		bool
	This flag modifies the ‘-rfn/-referenceNode’ and ‘-f/-filename’ flags to indicate the the children of the target reference will be returned. Returns a string array.
dagPath (dp)		bool
	This flag modifies the ‘-n/-nodes’ flag to indicate that the names of any dag objects returned will include as much of the dag path as is necessary to make the names unique. If this flag is not present, the names returned will not include any dag paths.
editAttrs (ea)		bool
	Returns string array. A main flag used to query the edits that have been applied to the target. Only the names of the attributes involved in the reference edit will be returned. If an edit involves multiple attributes (e.g. “connectAttr” edits) the nodes will be returned as separate, consecutive entries in the string array. A valid target is either a reference node, a reference file, or a referenced node. If a referenced node is specified, only those edits which affect that node will be returned. If a reference file or reference node is specified any edit which affects a node in that reference will be returned. If no target is specified all edits are returned. This command can be used on both loaded and unloaded references. By default it will return all the edits, formatted as MEL commands, which apply to the target. This flag can be used in combination with the ‘-ea/-editAttrs’ flag to indicate that the names of both the involved nodes and attributes will be returned in the format ‘node.attribute’.
editCommand (ec)		unicode
	This is a secondary flag used to indicate which type of reference edits should be considered by the command. If this flag is not specified all edit types will be included. This flag requires a string parameter. Valid values are: “addAttr”, “connectAttr”, “deleteAttr”, “disconnectAttr”, “parent”, “setAttr”, “lock” and “unlock”. In some contexts, this flag may be specified more than once to specify multiple edit types to consider.
editNodes (en)		bool
	Returns string array. A main flag used to query the edits that have been applied to the target. Only the names of the nodes involved in the reference edit will be returned. If an edit involves multiple nodes (e.g. “connectAttr” edits) the nodes will be returned as separate, consecutive entries in the string array. A valid target is either a reference node, a reference file, or a referenced node. If a referenced node is specified, only those edits which affect that node will be returned. If a reference file or reference node is specified any edit which affects a node in that reference will be returned. If no target is specified all edits are returned. This command can be used on both loaded and unloaded references. By default it will return all the edits, formatted as MEL commands, which apply to the target. This flag can be used in combination with the ‘-ea/-editAttrs’ flag to indicate that the names of both the involved nodes and attributes will be returned in the format ‘node.attribute’.
editStrings (es)		bool
	Returns string array. A main flag used to query the edits that have been applied to the target. The edit will be returned as a valid MEL command. A valid target is either a reference node, a reference file, or a referenced node. If a referenced node is specified, only those edits which affect that node will be returned. If a reference file or reference node is specified any edit which affects a node in that reference will be returned. If no target is specified all edits are returned. This command can be used on both loaded and unloaded references. By default it will return all the edits, formatted as MEL commands, which apply to the target. This flag cannot be used with either the ‘-en/-editNodes’ or ‘-ea/-editAttrs’ flags.
failedEdits (fld)		bool
	This is a secondary flag used to indicate whether or not failed edits should be acted on (e.g. queried, removed, etc...). A failed edit is an edit which could not be successfully applied the last time its reference was loaded. An edit can fail for a variety of reasons (e.g. the referenced node to which it applies was removed from the referenced file). By default failed edits will not be acted on.
filename (f)		bool
	Returns string. A main flag used to query the filename associated with the target reference.
isExportEdits (iee)		bool
	Returns a boolean indicating whether the specified reference node or file name is an edits file (created with the Export Edits feature)
isLoaded (il)		bool
	Returns a boolean indicating whether the specified reference node or file name refers to a loaded or unloaded reference.
isNodeReferenced (inr)		bool
	Returns boolean. A main flag used to determine whether or not the target node comes from a referenced file. true if the target node comes from a referenced file, false if not.
isPreviewOnly (ipo)		bool
	Returns boolean. This flag is used to determine whether or not the target reference node is only a preview reference node.
liveEdits (le)		bool
	Specifies that the edits should be returned based on the live edits database. Only valid when used in conjunction with the editStrings flag.
namespace (ns)		bool
	Returns string. This flag returns the full namespace path of the target reference, starting from the root namespace ”:”. It can be combined with the shortName flag to return just the base name of the namespace.
nodes (n)		bool
	Returns string array. A main flag used to query the contents of the target reference.
onReferenceNode (orn)		unicode
	This is a secondary flag used to indicate that only those edits which are stored on the indicated reference node should be considered. This flag only supports multiple uses when specified with the “exportEdits” command.Flag can appear in Create mode of commandFlag can have multiple arguments, passed either as a tuple or a list.
parent (p)		bool
	This flag modifies the ‘-rfn/-referenceNode’ and ‘-f/-filename’ flags to indicate the the parent of the target reference will be returned.
parentNamespace (pns)		bool
	A main flag used to query and return the parent namespace of the target reference.
referenceNode (rfn)		bool
	Returns string. A main flag used to query the reference node associated with the target reference.
shortName (shn)		bool
	This flag modifies the ‘-f/-filename’ and ‘-ns/-namespace’ flags. Used with the ‘-f/-filename’ flag indicates that the file name returned will be the short name (i.e. just a file name without any directory paths). If this flag is not present, the full name and directory path will be returned. Used with the ‘-ns/-namespace’ flag indicates that the namespace returned will be the base name of the namespace. (i.e. the base name of the full namespace path ”:AAA:BBB:CCC” is “CCC” )
showDagPath (sdp)		bool
	Shows/hides the full dag path for edits. If false only displays the node-name of reference edits. Must be used with the -editNodes, -editStrings or -editAttrs flag.
showNamespace (sns)		bool
	Shows/hides the namespaces on nodes in the reference edits. Must be used with the -editNodes, -editStrings or -editAttrs flag
successfulEdits (scs)		bool
	This is a secondary flag used to indicate whether or not successful edits should be acted on (e.g. queried, removed, etc...). A successful edit is any edit which was successfully applied the last time its reference was loaded. By default successful edits will be acted on.
topReference (tr)		bool
	This flag modifies the ‘-rfn/-referenceNode’ flag to indicate the top level ancestral reference of the target reference will be returned.
unresolvedName (un)		bool
	This flag modifies the ‘-f/-filename’ flag to indicate that the file name returned will be unresolved (i.e. it will be the path originally specified when the file was loaded into Maya; this path may contain environment variables and may not exist on disk). If this flag is not present, the resolved name will be returned.
withoutCopyNumber (wcn)		bool
	This flag modifies the ‘-f/-filename’ flag to indicate that the file name returned will not have a copy number (e.g. ‘{1}’) appended to the end. If this flag is not present, the file name returned may have a copy number appended to the end.

Derived from mel command maya.cmds.referenceQuery

Example:

import pymel.core as pm

# Build a sample scene:
# main scene contains a reference to mid.ma.
# mid.ma contains a reference to bot.ma.
# Create bot.ma with a poly sphere.
#
pm.polySphere()
# Result: [nt.Transform(u'pSphere1'), nt.PolySphere(u'polySphere1')] #
pm.file( rename='bot.ma' )
pm.file( f=True, s=True, type='mayaAscii')
# Create mid.ma with a poly cone.
# Reference bot.ma into mid.ma and group
# the sphere in bot.ma
#
pm.file( f=True, new=True )
pm.file( 'bot.ma', r=True,ns='bot' )
pm.polyCone()
pm.group( 'bot:pSphere1' )
pm.file( rename='mid.ma' )
pm.file( f=True, s=True, type='mayaAscii')
# Create a poly plane.
# Reference mid.ma into the main scene,
# move the cone in mid.ma, and connect
# the plane to the sphere in bot.ma.
#
pm.file( f=True, new=True )
pm.file( 'mid.ma', r=True, ns='mid' )
pm.select( 'mid:pCone1', r=True )
pm.move( 5, 5, 5, r=True )
pm.polyPlane()
pm.connectAttr( 'pPlane1.ty', 'mid:bot:polySphere1.radius' )
# Now perform some queries:
#
pm.referenceQuery( 'midRN',filename=True )
# Result: C:/Documents and Settings/user/My Documents/maya/projects/default/scenes/mid.ma
pm.referenceQuery( 'mid:pCone1', filename=True, shortName=True )
# Result: mid.ma
pm.referenceQuery( 'mid:botRN', filename=True, parent=True )
# Result: C:/Documents and Settings/user/My Documents/maya/projects/default/scenes/mid.ma
pm.referenceQuery( 'mid.ma', referenceNode=True )
# Result: midRN
pm.referenceQuery( 'C:/Documents and Settings/user/My Documents/maya/projects/default/scenes/bot.ma', referenceNode=True)
# Result: mid:botRN
pm.referenceQuery( 'bot.ma', referenceNode=True, parent=True )
# Result: midRN
pm.referenceQuery( 'bot.ma', referenceNode=True, topReference=True )
# Result: midRN
pm.referenceQuery( 'mid:botRN',nodes=True )
[u'mid:bot:pPlane1', u'mid:bot:pPlaneShape1', u'mid:bot:outputCloth1', u'mid:bot:nCloth1', u'mid:bot:nClothShape1', u'mid:bot:dynamicConstraint1', u'mid:bot:dynamicConstraintShape1', u'mid:bot:nurbsSphere1', u'mid:bot:nurbsSphereShape1', u'mid:bot:pSphere1', u'mid:bot:pSphereShape1', u'mid:bot:lightLinker1', u'mid:bot:layerManager', u'mid:bot:defaultLayer', u'mid:bot:renderLayerManager', u'mid:bot:defaultRenderLayer', u'mid:bot:polyPlane1', u'mid:bot:nucleus1', u'mid:bot:nComponent1', u'mid:bot:uiConfigurationScriptNode', u'mid:bot:sceneConfigurationScriptNode', u'mid:bot:nClothShape1Cache1Start', u'mid:bot:cacheBlend1', u'mid:bot:nClothShape1Cache2', u'mid:bot:nClothShape1Cache1End', u'mid:bot:makeNurbSphere1', u'mid:bot:polySphere1']
pm.referenceQuery( 'pPlane1', isNodeReferenced=True )
# Result: 0
pm.referenceQuery( 'mid:pCone1', isNodeReferenced=True )
# Result: 1
pm.referenceQuery( 'mid:botRN', parentNamespace=True )
# Result: mid
pm.referenceQuery( 'mid:bot:pSphere1', parentNamespace=True )
# Result: mid
pm.referenceQuery( 'C:/Documents and Settings/user/My Documents/maya/projects/default/scenes/bot.ma', parentNamespace=True )
# Result: mid
print pm.referenceQuery( 'bot.ma', namespace=True )
# Result: :mid:bot
print pm.referenceQuery( 'mid:botRN', namespace=True )
# Result: :mid:bot
print pm.referenceQuery( 'bot.ma', namespace=True, shortName=True )
# Result: bot
print pm.referenceQuery( 'mid.ma', namespace=True )
# Result: :mid
print pm.referenceQuery( 'mid.ma', namespace=True, shortName=True )
# Result: mid