mrv.maya.ref

Epydoc: mrv.maya.ref

Allows convenient access and handling of references in an object oriented manner

Functions

mrv.maya.ref._isRootOf(root, other)

Returns:

True if other which may be a string, is rooted at ‘root

Parameters:

• other – ‘’ = root namespace’ hello:world => :hello:world
• root – may be namespace or string. It must not have a ‘:’ in front, hence it must be a relative naespace, and must end with a ‘:’.

Note:

the arguments are very specific, but this allows the method to be faster than usual

mrv.maya.ref.createReference(*args, **kwargs)

create a new reference, see FileReference.create for more information

mrv.maya.ref.listReferences(*args, **kwargs)

List intermediate references of in the scene, see FileReference.ls for more information

mrv.maya.ref.make_path(path)

Returns:A path instance of the correct type Note:use this constructor if you use the Path.set_separator method at runtime to assure you will always create instances of the actual type, and not only of the type you imported last

mrv.maya.ref.noneToList(res)

Returns:list instead of None

Classes

Epydoc: mrv.maya.ref

class mrv.maya.ref.And(*args)

Bases: object

For use with python’s filter method, simulates logical AND Usage: filter(And(f1,f2,fn), sequence)

functions

Epydoc: mrv.maya.ref.FileReference

class mrv.maya.ref.FileReference(filepath=None, refnode=None)

Bases: mrv.interface.iDagItem

Represents a Maya file reference

Note:do not cache these instances but get a fresh one when you have to work with it Note:as FileReference is also a iDagItem, all the respective methods, especially for parent/child iteration and query can be used as well

classmethod addSep(item, sep)

Returns:

item with separator added to it ( just once )

Note:

operates best on strings

Parameters:

• item – item to add separator to
• sep – the separator

basename()

Returns:basename of this path, ‘/hello/world’ -> ‘world’

children(predicate=<function <lambda> at 0x5c4c578>)

Returns:all intermediate child references of this instance

childrenDeep(order=1, predicate=<function <lambda> at 0x7f41dd7c5050>)

Returns:

list of all children of path, [ child1 , child2 ]

Parameters:

• order – order enumeration
• predicate – returns true if x may be returned

Note:

the child objects returned are supposed to be valid paths, not just relative paths

cleanup(*args, **kwargs)

remove unresolved edits or all edits on this reference

Parameters:

• unresolvedEdits – if True, only dangling connections will be removed, if False, all reference edits will be removed - the reference will be unloaded for beforehand. The loading state of the reference will stay unchanged after the operation.
• editTypes – list of edit types to remove during cleanup

Returns:

self

copynumber()

Returns:the references copy number - starting at 0 for the first reference Note:we do not cache the copy number as mayas internal numbering can change on when references change - the only stable thing is the reference node name

classmethod create(filepath, namespace=None, load=True, **kwargs)

Create a reference with the given namespace

Parameters:

• filepath – path describing the reference file location
• namespace – if None, a unique namespace will be generated for you The namespace will contain all referenced objects.
• load – if True, the reference will be created in loaded state, other wise its loading is deferred
• kwargs – passed to file command

Raises ValueError:  

if the namespace does already exist

Raises RuntimeError:  

if the reference could not be created

exists()

Returns:True if our file reference exists in maya

classmethod fromPaths(paths, **kwargs)

Find the reference for each path in paths. If you provide the path X 2 times, but you only have one reference to X, the return value will be [FileReference(X), None] as there are less references than provided paths.

Parameters:

• paths – a list of paths or references whose references in the scene should be returned. In case a reference is found, its plain path will be used instead.
• kwargs –

  all supported by ls to yield the base set of references we will use to match the paths with. Additionally, you may specify:

  • ignore_extension:

    if True, default False, the extension will be ignored during the search, only the actual base name will matter. This way, an MA file will be matched with an MB file. The references returned will still have their extension original extension.

Returns:

list(FileReference|None, ...) if a filereference was found for given occurrence of Path, it will be returned at index of the current path in the input paths, otherwise it is None.

Note:

zip(paths, result) to get a corresponding tuple list associating each input path with the located reference

fullChildName(childname)

Add the given name to the string version of our instance :return: string with childname added like name _sep childname

importRef(*args, **kwargs)

Import the reference until the given depth is reached

Parameter:depth –

• x<1: import all references and subreferences

• x: import until level x is reached, 0 imports just self such that

  all its children are on the same level as self was before import

Returns:list of FileReference objects that are now in the root namespace - this list could be empty if all subreferences are fully imported

isLoaded()

Returns:True if the reference is loaded

isLocked()

Returns:True if reference is locked

isPartOf(other)

Returns:True if self is a part of other, and thus can be found in other Note:operates on strings only

isRoot()

Returns:True if this path is the root of the DAG

isRootOf(other)

Returns:True other starts with self Note:operates on strings Note:we assume other has the same type as self, thus the same separator

iterNodes(*args, **kwargs)

Creates iterator over nodes in this reference

Parameters:

• args – MFn.kType filter ids to be used to pre-filter all nodes. If you know what you are looking for, setting this can greatly improve performance !
• kwargs –

  additional kwargs will be passed to either iterDagNodes or iterDgNodes (dag = False). The following additional kwargs may be specified:

  • asNode:

    if True, default True, return wrapped Nodes, if False MDagPaths or MObjects will be returned

  • dag:

    if True, default False, return dag nodes only. Otherwise return dependency nodes as well. Enables assemblies and assembilesInReference.

  • assemblies:

    if True, return only dagNodes with no parent. Needs dag and is mutually exclusive with assembilesInReference.

  • assembliesInReference:

    if True, return only dag nodes that have no parent in their own reference. They may have a parent not coming from their reference though. This flag has a big negative performance impact and requires dag.

  • predicate:

    if function returns True for Node|MObject|MDagPath n, n will be yielded. Defaults to return True for all.

Raises ValueError:  

if incompatible arguments have been given

iterParents(predicate=<function <lambda> at 0x7f41dd7c5230>)

Returns:generator retrieving all parents up to the root Parameter:predicate – returns True for all x that you want to be returned

classmethod ls(rootReference='', predicate=<function <lambda> at 0x5c4be60>)

list all references in the scene or under the given root

Parameters:

• rootReference – if not empty, the references below it will be returned. Otherwise all scene references will be listed. May be string, Path or FileReference
• predicate – method returning true for each valid file reference object that should be part of the return value.

Returns:

list of FileReference s objects

classmethod lsDeep(predicate=<function <lambda> at 0x5c4bf50>, **kwargs)

Return all references recursively

Parameter:kwargs – support for arguments as in ls, hence you can use the rootReference flag to restrict the set of returned FileReferences.

namespace()

Returns:namespace object of the full namespace holding all objects in this reference

parent()

Returns:the parent reference of this instance or None if we are root

parentDeep()

Returns:all parents of this path, ‘/hello/my/world’ -> [ ‘/hello/my’,’/hello’ ]

path(copynumber=False, unresolved=False)

Returns:

Path object with the path containing the reference’s data

Parameters:

• copynumber – If True, the returned path will include the copy number. As it will be a path object, it might not be fully usable in that state
• unresolved – see ls

Note:

we always query it from maya as our numbers change if some other reference is being removed and cannot be trusted

referenceNode()

Returns:wrapped reference node managing this reference

remove(*args, **kwargs)

Remove the given reference from the scene

Note:assures that no namespaces of that reference are left, remaining objects will be moved into the root namespace. This way the namespaces will not be left as waste. This fails if there are referenced objects in the subnamespace - we currently ignore that issue as the main reference removal worked at that point. Note:kwargs passed to namespace.delete

replace(*args, **kwargs)

Replace this reference with filepath

Parameter:filepath – the path to the file to replace this reference with Reference instances will be handled as well. Returns:self

root()

Returns:the root of the DAG - it has no further parents

setLoaded(*args, **kwargs)

set the reference loaded or unloaded

Parameter:state – True = unload reference, True = load reference Returns:self

setLocked(*args, **kwargs)

Set the reference to be locked or unlocked

Parameter:state – if True, the reference is locked , if False its unlocked and can be altered Returns:self

setNamespace(*args, **kwargs)

set the reference to use the given namespace

Parameter:namespace – Namespace instance or name of the short namespace Raises RuntimeError:  if namespace already exists or if reference is not root Returns:self

supports(interface_type)

Returns:True if this instance supports the interface of the given type Parameter:interface_type – Type of the interface you require this instance to support Note:Must be used in case you only have a weak reference of your interface instance or proxy which is a case where the ordinary isinstance( obj, iInterface ) will not work

Epydoc: mrv.maya.ref

class mrv.maya.ref.Namespace

Bases: unicode, mrv.interface.iDagItem

Represents a Maya namespace Namespaces follow the given nameing conventions:

• Paths starting with a column are absolute

• :absolute:path

• Path separator is ‘:’

classmethod addSep(item, sep)

Returns:

item with separator added to it ( just once )

Note:

operates best on strings

Parameters:

• item – item to add separator to
• sep – the separator

basename()

Returns:basename of this path, ‘/hello/world’ -> ‘world’

capitalize

S.capitalize() -> unicode

Return a capitalized version of S, i.e. make the first character have upper case.

center

S.center(width[, fillchar]) -> unicode

Return S centered in a Unicode string of length width. Padding is done using the specified fill character (default is a space)

children(predicate=<function <lambda> at 0x5c445f0>)

Returns:list of child namespaces Parameter:predicate – return True to include x in result

childrenDeep(order=1, predicate=<function <lambda> at 0x7f41dd7c5050>)

Returns:

list of all children of path, [ child1 , child2 ]

Parameters:

• order – order enumeration
• predicate – returns true if x may be returned

Note:

the child objects returned are supposed to be valid paths, not just relative paths

count

S.count(sub[, start[, end]]) -> int

Return the number of non-overlapping occurrences of substring sub in Unicode string S[start:end]. Optional arguments start and end are interpreted as in slice notation.

classmethod create(*args, **kwargs)

Create a new namespace

Parameter:namespaceName – the name of the namespace, absolute or relative - it may contain subspaces too, i.e. :foo:bar. fred:subfred is a relative namespace, created in the currently active namespace Note:if the target namespace already exists, it will be returned Returns:the create Namespace object

classmethod current()

Returns:the currently set absolute namespace

decode

S.decode([encoding[,errors]]) -> string or unicode

Decodes S using the codec registered for encoding. encoding defaults to the default encoding. errors may be given to set a different error handling scheme. Default is ‘strict’ meaning that encoding errors raise a UnicodeDecodeError. Other possible values are ‘ignore’ and ‘replace’ as well as any other name registerd with codecs.register_error that is able to handle UnicodeDecodeErrors.

defaultIncrFunc(b, i)

%s%02i

delete(move_to_namespace=':', autocreate=True)

Delete this namespace and move it’s obejcts to the given move_to_namespace

Parameters:

• move_to_namespace – if None, the namespace to be deleted must be empty If Namespace, objects in this namespace will be moved there prior to namespace deletion move_to_namespace must exist
• autocreate – if True, move_to_namespace will be created if it does not exist yet

Note:

can handle sub-namespaces properly

Raises RuntimeError:   Todo:

Implement undo !

encode

S.encode([encoding[,errors]]) -> string or unicode

Encodes S using the codec registered for encoding. encoding defaults to the default encoding. errors may be given to set a different error handling scheme. Default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

endswith

S.endswith(suffix[, start[, end]]) -> bool

Return True if S ends with the specified suffix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. suffix can also be a tuple of strings to try.

exists()

Returns:True if this namespace exists

expandtabs

S.expandtabs([tabsize]) -> unicode

Return a copy of S where all tab characters are expanded using spaces. If tabsize is not given, a tab size of 8 characters is assumed.

find

S.find(sub [,start [,end]]) -> int

Return the lowest index in S where substring sub is found, such that sub is contained within s[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

classmethod findUnique(basename, incrementFunc=<function <lambda> at 0x5c3e488>)

Find a unique namespace based on basename which does not yet exist in the scene and can be created.

Parameters:

• basename – basename of the namespace, like “:mynamespace” or “mynamespace:subspace”
• incrementFunc – func( basename, index ), returns a unique name generated from the basename and the index representing the current iteration

Returns:

unique namespace that is guaranteed not to exist below the current namespace

format

S.format(*args, **kwargs) -> unicode

fullChildName(childname)

Add the given name to the string version of our instance :return: string with childname added like name _sep childname

index

S.index(sub [,start [,end]]) -> int

Like S.find() but raise ValueError when the substring is not found.

isAbsolute()

Returns:True if this namespace is an absolut one, defining a namespace from the root namespace like “:foo:bar

isPartOf(other)

Returns:True if self is a part of other, and thus can be found in other Note:operates on strings only

isRoot()

Returns:True if this path is the root of the DAG

isRootOf(other)

Returns:True other starts with self Note:operates on strings Note:we assume other has the same type as self, thus the same separator

isalnum

S.isalnum() -> bool

Return True if all characters in S are alphanumeric and there is at least one character in S, False otherwise.

isalpha

S.isalpha() -> bool

Return True if all characters in S are alphabetic and there is at least one character in S, False otherwise.

isdecimal

S.isdecimal() -> bool

Return True if there are only decimal characters in S, False otherwise.

isdigit

S.isdigit() -> bool

Return True if all characters in S are digits and there is at least one character in S, False otherwise.

islower

S.islower() -> bool

Return True if all cased characters in S are lowercase and there is at least one cased character in S, False otherwise.

isnumeric

S.isnumeric() -> bool

Return True if there are only numeric characters in S, False otherwise.

isspace

S.isspace() -> bool

Return True if all characters in S are whitespace and there is at least one character in S, False otherwise.

istitle

S.istitle() -> bool

Return True if S is a titlecased string and there is at least one character in S, i.e. upper- and titlecase characters may only follow uncased characters and lowercase characters only cased ones. Return False otherwise.

isupper

S.isupper() -> bool

Return True if all cased characters in S are uppercase and there is at least one cased character in S, False otherwise.

iterNodes(*args, **kwargs)

Return an iterator on all objects in the namespace

Parameters:

• args – MFn.kType filter types to be used to pre-filter the nodes in the namespace. This can greatly improve performance !
• kwargs –

  given to iterDagNodes or iterDgNodes, which includes the option to provide a predicate function. Additionally, the following ones may be defined:

  • asNode:

    if true, default True, Nodes will be yielded. If False, you will receive MDagPaths or MObjects depending on the ‘dag’ kwarg

  • dag:

    if True, default False, only dag nodes will be returned, otherwise you will receive dag nodes and dg nodes. Instance information will be lost on the way though.

  • depth:

    if 0, default 0, only objects in this namespace will be returned

    if -1, all subnamespaces will be included as well, the depth is unlimited

    if 0<depth<x include all objects up to the ‘depth’ subnamespace

Note:

this method is quite similar to FileReference.iterNodes, but has a different feature set and needs this code here for maximum performance

iterParents(predicate=<function <lambda> at 0x7f41dd7c5230>)

Returns:generator retrieving all parents up to the root Parameter:predicate – returns True for all x that you want to be returned

join

S.join(iterable) -> unicode

Return a string which is the concatenation of the strings in the iterable. The separator between elements is S.

ljust

S.ljust(width[, fillchar]) -> int

Return S left-justified in a Unicode string of length width. Padding is done using the specified fill character (default is a space).

lower

S.lower() -> unicode

Return a copy of the string S converted to lowercase.

lstrip

S.lstrip([chars]) -> unicode

Return a copy of the string S with leading whitespace removed. If chars is given and not None, remove characters in chars instead. If chars is a str, it will be converted to unicode before stripping

moveNodes(targetNamespace, force=True, autocreate=True)

Move objects from this to the targetNamespace

Parameters:

• force – if True, namespace clashes will be resolved by renaming, if false possible clashes would result in an error
• autocreate – if True, targetNamespace will be created if it does not exist yet

Todo:

Implement undo !

parent()

Returns:parent namespace of this instance

parentDeep()

Returns:all parents of this path, ‘/hello/my/world’ -> [ ‘/hello/my’,’/hello’ ]

partition

S.partition(sep) -> (head, sep, tail)

Search for the separator sep in S, and return the part before it, the separator itself, and the part after it. If the separator is not found, return S and two empty strings.

relativeTo(basenamespace)

returns this namespace relative to the given basenamespace

Parameter:basenamespace – the namespace to which the returned one should be relative too Raises ValueError:  If this or basenamespace is not absolute or if no relative namespace exists Returns:relative namespace

rename(newName)

Rename this namespace to newName - the original namespace will cease to exist

Note:if the namespace already exists, the existing one will be returned with all objects from this one added accordingly Parameter:newName – the absolute name of the new namespace Returns:Namespace with the new name Todo:Implement undo !

replace

S.replace (old, new[, count]) -> unicode

Return a copy of S with all occurrences of substring old replaced by new. If the optional argument count is given, only the first count occurrences are replaced.

rfind

S.rfind(sub [,start [,end]]) -> int

Return the highest index in S where substring sub is found, such that sub is contained within s[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

rindex

S.rindex(sub [,start [,end]]) -> int

Like S.rfind() but raise ValueError when the substring is not found.

rjust

S.rjust(width[, fillchar]) -> unicode

Return S right-justified in a Unicode string of length width. Padding is done using the specified fill character (default is a space).

root()

Returns:the root of the DAG - it has no further parents

rpartition

S.rpartition(sep) -> (head, sep, tail)

Search for the separator sep in S, starting at the end of S, and return the part before it, the separator itself, and the part after it. If the separator is not found, return two empty strings and S.

rsplit

S.rsplit([sep [,maxsplit]]) -> list of strings

Return a list of the words in S, using sep as the delimiter string, starting at the end of the string and working to the front. If maxsplit is given, at most maxsplit splits are done. If sep is not specified, any whitespace string is a separator.

rstrip

S.rstrip([chars]) -> unicode

Return a copy of the string S with trailing whitespace removed. If chars is given and not None, remove characters in chars instead. If chars is a str, it will be converted to unicode before stripping

setCurrent(*args, **kwargs)

Set this namespace to be the current one - new objects will be put in it by default

Returns:self

split

S.split([sep [,maxsplit]]) -> list of strings

Return a list of the words in S, using sep as the delimiter string. If maxsplit is given, at most maxsplit splits are done. If sep is not specified or is None, any whitespace string is a separator and empty strings are removed from the result.

classmethod splitNamespace(objectname)

Cut the namespace from the given name and return a tuple( namespacename, objectname )

Note:method assumes that the namespace starts at the beginning of the object

splitlines

S.splitlines([keepends]) -> list of strings

Return a list of the lines in S, breaking at line boundaries. Line breaks are not included in the resulting list unless keepends is given and true.

startswith

S.startswith(prefix[, start[, end]]) -> bool

Return True if S starts with the specified prefix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. prefix can also be a tuple of strings to try.

strip

S.strip([chars]) -> unicode

Return a copy of the string S with leading and trailing whitespace removed. If chars is given and not None, remove characters in chars instead. If chars is a str, it will be converted to unicode before stripping

substitute(find_in, replacement)

Returns:string with our namespace properly substituted with replacement such that the result is a properly formatted object name ( with or without namespace depending of the value of replacement ) As this method is based on string replacement, self might as well match sub-namespaces if it is relative Note:if replacement is an empty string, it will effectively cut the matched namespace off the object name Note:handles replacement of subnamespaces correctly as well Note:as it operates on strings, the actual namespaces do not need to exist

classmethod substituteNamespace(thisns, find_in, replacement)

Same as substitute, but signature might feel more natural

supports(interface_type)

Returns:True if this instance supports the interface of the given type Parameter:interface_type – Type of the interface you require this instance to support Note:Must be used in case you only have a weak reference of your interface instance or proxy which is a case where the ordinary isinstance( obj, iInterface ) will not work

swapcase

S.swapcase() -> unicode

Return a copy of S with uppercase characters converted to lowercase and vice versa.

title

S.title() -> unicode

Return a titlecased version of S, i.e. words start with title case characters, all remaining cased characters have lower case.

toRelative()

Returns:a relative version of self, thus it does not start with a colon Note:the root namespace cannot be relative - if this is of interest for you, you have to check for it. This method gracefully ignores that fact to make it more convenient to use as one does not have to be afraid of exceptions

translate

S.translate(table) -> unicode

Return a copy of the string S, where all characters have been mapped through the given translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, Unicode strings or None. Unmapped characters are left untouched. Characters mapped to None are deleted.

upper

S.upper() -> unicode

Return a copy of S converted to uppercase.

zfill

S.zfill(width) -> unicode

Pad a numeric string S with zeros on the left, to fill a field of the specified width. The string S is never truncated.

Epydoc: mrv.maya.ref

class mrv.maya.ref.iDagItem

Bases: mrv.interface.Interface

Describes interface for a DAG item. Its used to unify interfaces allowing to access objects in a dag like graph Of the underlying object has a string representation, the defatult implementation will work natively. Otherwise the getParent and getChildren methods should be overwritten

Note:a few methods of this class are abstract and need to be overwritten Note:this class expects the attribute ‘_sep’ to exist containing the separator at which your object should be split ( for default implementations ). This works as the passed in pointer will belong to derived classes that can define that attribute on instance or on class level

classmethod addSep(item, sep)

Returns:

item with separator added to it ( just once )

Note:

operates best on strings

Parameters:

• item – item to add separator to
• sep – the separator

basename()

Returns:basename of this path, ‘/hello/world’ -> ‘world’

children(predicate=<function <lambda> at 0x7f41dd7c2ed8>)

Returns:list of intermediate children of path, [ child1 , child2 ] Parameter:predicate – return True to include x in result Note:the child objects returned are supposed to be valid paths, not just relative paths

childrenDeep(order=1, predicate=<function <lambda> at 0x7f41dd7c5050>)

Returns:

list of all children of path, [ child1 , child2 ]

Parameters:

• order – order enumeration
• predicate – returns true if x may be returned

Note:

the child objects returned are supposed to be valid paths, not just relative paths

fullChildName(childname)

Add the given name to the string version of our instance :return: string with childname added like name _sep childname

isPartOf(other)

Returns:True if self is a part of other, and thus can be found in other Note:operates on strings only

isRoot()

Returns:True if this path is the root of the DAG

isRootOf(other)

Returns:True other starts with self Note:operates on strings Note:we assume other has the same type as self, thus the same separator

iterParents(predicate=<function <lambda> at 0x7f41dd7c5230>)

Returns:generator retrieving all parents up to the root Parameter:predicate – returns True for all x that you want to be returned

parent()

Returns:parent of this path, ‘/hello/world’ -> ‘/hello’ or None if this path is the dag’s root

parentDeep()

Returns:all parents of this path, ‘/hello/my/world’ -> [ ‘/hello/my’,’/hello’ ]

root()

Returns:the root of the DAG - it has no further parents

supports(interface_type)

Returns:True if this instance supports the interface of the given type Parameter:interface_type – Type of the interface you require this instance to support Note:Must be used in case you only have a weak reference of your interface instance or proxy which is a case where the ordinary isinstance( obj, iInterface ) will not work

Epydoc: mrv.maya.ref

class mrv.maya.ref.ifilter

Bases: object

ifilter(function or None, sequence) –> ifilter object

Return those items of sequence for which function(item) is true. If function is None, return the items that are true.

next

x.next() -> the next value, or raise StopIteration

Exceptions

Epydoc: mrv.maya.ref.FileReferenceError

class mrv.maya.ref.FileReferenceError(*args, **kwargs)

Bases: mrv.exc.MRVError

args

message

Epydoc: mrv.maya.ref

class mrv.maya.ref.MRVError(*args, **kwargs)

Bases: exceptions.Exception

Base Class for all exceptions that the mrv framework throws

args

message