pymel.core.system.FileReference¶

class FileReference(pathOrRefNode=None, namespace=None, refnode=None)¶

A class for manipulating references which inherits Path and path. you can create an instance by supplying the path to a reference file, its namespace, or its reference node to the appropriate keyword. The namespace and reference node of the reference can be retreived via the namespace and refNode properties. The namespace property can also be used to change the namespace of the reference.

Use listReferences command to return a list of references as instances of the FileReference class.

It is important to note that instances of this class will have their copy number stripped off and stored in an internal variable upon creation. This is to maintain compatibility with the numerous methods inherited from the path class which requires a real file path. When calling built-in methods of FileReference, the path will automatically be suffixed with the copy number before being passed to maya commands, thus ensuring the proper results in maya as well.

clean(**kwargs)¶

Remove edits from the passed in reference node. The reference must be in an unloaded state. To remove a particular type of edit, use the editCommand flag. If no flag is specified, all edits will be removed.

Flags:

• editCommand:

  For use with cleanReference. Remove only this type of edit. Supported edits are: setAttr addAttr deleteAttr connectAttr disconnectAttr and parent

Derived from mel command maya.cmds.file

copyNumberList()¶

When queried, this flag returns a string array containing a number that uniquely identifies each instance the file is used.

Derived from mel command maya.cmds.file

exportAnim(exportPath, **kwargs)¶

Export the main scene animation nodes and animation helper nodes from all referenced objects. This flag, when used in conjunction with the -rfn/referenceNode flag, can be constrained to only export animation nodes from the specified reference file. See -ean/exportAnim flag description for details on usage of animation files.

Flags:

• force:

  Force an action to take place. (new, open, save, remove reference, unload reference) Used with removeReference to force remove reference namespace even if it has contents. Cannot be used with removeReference if the reference resides in the root namespace. Used with unloadReference to force unload reference even if the reference node is locked, without prompting a dialog that warns user about the lost of edits.

• referenceNode:

  This flag is only used during queries. In MEL, if it appears before -query then it must be followed by the name of one of the scene’s reference nodes. That will determine the reference to be queried by whatever flags appear after -query. If the named reference node does not exist within the scene the command will fail with an error. In Python the equivalent behavior is obtained by passing the name of the reference node as the flag’s value. In MEL, if this flag appears after -query then it takes no argument and will cause the command to return the name of the reference node associated with the file given as the command’s argument. If the file is not a reference or for some reason does not have a reference node (e.g., the user deleted it) then an empty string will be returned. If the file is not part of the current scene then the command will fail with an error. In Python the equivalent behavior is obtained by passing True as the flag’s value. In query mode, this flag can accept a value.

• type:

  Set the type of this file. By default this can be any one of: mayaAscii, mayaBinary, mel, OBJ, directory, plug-in, audio, move, EPS, Adobe(R) Illustrator(R), imageplug-ins may define their own types as well.Return a string array of file types that match this file.

Derived from mel command maya.cmds.file

exportSelectedAnim(exportPath, **kwargs)¶

Export the main scene animation nodes and animation helper nodes from the selected referenced objects. This flag, when used in conjunction with the -rfn/referenceNode flag, can be constrained to only export animation nodes from the selected nodes of a specified reference file. See -ean/exportAnim flag description for details on usage of animation files.

Flags:

• force:

  Force an action to take place. (new, open, save, remove reference, unload reference) Used with removeReference to force remove reference namespace even if it has contents. Cannot be used with removeReference if the reference resides in the root namespace. Used with unloadReference to force unload reference even if the reference node is locked, without prompting a dialog that warns user about the lost of edits.

• referenceNode:

  This flag is only used during queries. In MEL, if it appears before -query then it must be followed by the name of one of the scene’s reference nodes. That will determine the reference to be queried by whatever flags appear after -query. If the named reference node does not exist within the scene the command will fail with an error. In Python the equivalent behavior is obtained by passing the name of the reference node as the flag’s value. In MEL, if this flag appears after -query then it takes no argument and will cause the command to return the name of the reference node associated with the file given as the command’s argument. If the file is not a reference or for some reason does not have a reference node (e.g., the user deleted it) then an empty string will be returned. If the file is not part of the current scene then the command will fail with an error. In Python the equivalent behavior is obtained by passing True as the flag’s value. In query mode, this flag can accept a value.

• type:

  Set the type of this file. By default this can be any one of: mayaAscii, mayaBinary, mel, OBJ, directory, plug-in, audio, move, EPS, Adobe(R) Illustrator(R), imageplug-ins may define their own types as well.Return a string array of file types that match this file.

Derived from mel command maya.cmds.file

fullNamespace¶

getReferenceEdits(**kwargs)¶

Get a list of ReferenceEdit objects for this node

Adapted from: referenceQuery -editString -onReferenceNode <self.refNode>

Notes

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.

importContents(removeNamespace=False)¶

Remove the encapsulation of the reference around the data within the specified file. This makes the contents of the specified file part of the current scene and all references to the original file are lost. Returns the name of the reference that was imported.

Derived from mel command maya.cmds.file

isDeferred()¶

When used in conjunction with the -reference flag, this flag determines if the reference is loaded, or if loading is deferred.C: The default is false.Q: When queried, this flag returns true if the reference is deferred, or false if the reference is not deferred. If this is used with -rfn/referenceNode, the -rfn flag must come before -q.

Derived from mel command maya.cmds.file

isLoaded()¶

When used in conjunction with the -reference flag, this flag determines if the reference is loaded, or if loading is deferred.C: The default is false.Q: When queried, this flag returns true if the reference is deferred, or false if the reference is not deferred. If this is used with -rfn/referenceNode, the -rfn flag must come before -q.

Derived from mel command maya.cmds.file

isUsingNamespaces()¶

Returns boolean. Queries whether the specified reference file uses namespaces or renaming prefixes.

Derived from mel command maya.cmds.file

load(newFile=None, **kwargs)¶

This flag loads a file and associates it with the passed reference node. If the reference node does not exist, the command will fail. If the file is already loaded, then this flag will reload the same file.If a file is not given, the command will load (or reload) the last used reference file.

Flags:

• loadNoReferences:

  This flag is obsolete and has been replaced witht the loadReferenceDepth flag. When used with the -open flag, no references will be loaded. When used with -i/import, -r/reference or -lr/loadReference flags, will load the top-most reference only.

• loadReferenceDepth:

  Used to specify which references should be loaded. Valid types are all, noneand topOnly, which will load all references, no references and top-level references only, respectively. May only be used with the -o/open, -i/import, -r/reference or -lr/loadReference flags. When noneis used with -lr/loadReference, only path validation is performed. This can be used to replace a reference without triggering reload. Not using loadReferenceDepth will load references in the same loaded or unloaded state that they were in when the file was saved. Additionally, the -lr/loadReference flag supports a fourth type, asPrefs. This will force any nested references to be loaded according to the state (if any) stored in the current scene file, rather than according to the state saved in the reference file itself.

• returnNewNodes:

  Used to control the return value in open, import, loadReference, and reference operations. It will force the file command to return a list of new nodes added to the current scene.

Derived from mel command maya.cmds.file

lock()¶

Locks attributes and nodes from the referenced file.

Derived from mel command maya.cmds.file

namespace¶

namespaceExists()¶

Returns true if the specified namespace exists, false if not.

Derived from mel command maya.cmds.namespace

nodes()¶

Returns string array. A main flag used to query the contents of the target reference.

Derived from mel command maya.cmds.referenceQuery

parent()¶

Returns the parent FileReference object, or None

path¶

refNode¶

remove()¶

Remove the given file reference from its parent. This will also Remove everything this file references. Returns the name of the file removed. If the reference is alone in its namespace, remove the namespace. If there are objects remaining in the namespace after the file reference is removed, by default, keep the remaining objects in the namespace. To merge the objects remaining in the namespace to the parent or root namespace, use flags mergeNamespaceWithParent or mergeNamespaceWithRoot. The empty file reference namespace is then removed. To forcibly delete all objects, use flag force. The empty file reference namespace is then removed.

Derived from mel command maya.cmds.file

removeReferenceEdits(editCommand=None, force=False, **kwargs)¶

Remove edits from the reference.

Parameters:	editCommand (str) – If specified, remove only edits of a particular type: addAttr, setAttr, connectAttr, disconnectAttr or parent force (bool) – Unload the reference if it is not unloaded already successfulEdits (bool) – Whether to remove successful edits failedEdits (bool) – Whether to remove failed edits

Notes

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. This will only succeed on unapplied edits (ie, on unloaded nodes, or failed edits)... However, like maya.cmds.file/maya.cmds.referenceEdit, no error will be raised if there are no unapplied edits to work on. This may change in the future, however...

replaceWith(newFile, **kwargs)¶

This flag loads a file and associates it with the passed reference node. If the reference node does not exist, the command will fail. If the file is already loaded, then this flag will reload the same file.If a file is not given, the command will load (or reload) the last used reference file.

Flags:

• loadNoReferences:

  This flag is obsolete and has been replaced witht the loadReferenceDepth flag. When used with the -open flag, no references will be loaded. When used with -i/import, -r/reference or -lr/loadReference flags, will load the top-most reference only.

• loadReferenceDepth:

  Used to specify which references should be loaded. Valid types are all, noneand topOnly, which will load all references, no references and top-level references only, respectively. May only be used with the -o/open, -i/import, -r/reference or -lr/loadReference flags. When noneis used with -lr/loadReference, only path validation is performed. This can be used to replace a reference without triggering reload. Not using loadReferenceDepth will load references in the same loaded or unloaded state that they were in when the file was saved. Additionally, the -lr/loadReference flag supports a fourth type, asPrefs. This will force any nested references to be loaded according to the state (if any) stored in the current scene file, rather than according to the state saved in the reference file itself.

• returnNewNodes:

  Used to control the return value in open, import, loadReference, and reference operations. It will force the file command to return a list of new nodes added to the current scene.

Derived from mel command maya.cmds.file

selectAll()¶

Select all the components of this file as well as its child files. Note that the file specified must be one that is already opened in this Maya session. The default behavior is to replace the existing selection. Use with the addflag to keep the active selection list.

Derived from mel command maya.cmds.file

subReferences()¶

unload()¶

This flag will unload the reference file associated with the passed reference node.

Derived from mel command maya.cmds.file

unlock()¶

Locks attributes and nodes from the referenced file.

Derived from mel command maya.cmds.file

unresolvedPath()¶

withCopyNumber()¶

return the path with the copy number at the end