PyMEL for Maya¶

Changes¶

• general: MultiAttrs now support __delitem__
• uitype: use PySide in toQtObject methods if no PyQt
• language: added mel.globals alias for melGlobals
• core: improve API undo callbacks
• system: saveFile resets name if filename is messed up
• system: make loadReference give more informative error if ref not loaded
• system: optimized FileReference.__init__
• system: switched file cmd used by iterReferences for more stable referenceQuery
• docs: improved the look of the docs
• util.arrays: Array objects now explicitly unhashable, added totuple
• utils.path: allow the pattern argument for various methods to take a compiled regular expression pattern.

Additions¶

• language: added Env.playbackTimes convenience property for getting/setting all timeline values at once
• allapi: added example usage to SafeApiPtr
• general: added Attribute.iterDescendants
• system: added mode and caseSensitive args to Translator.fromExtension
• nodetypes: added topLevel and descendants kwargs to DependNode.listAttr
• nodetypes: added Camera.isDisplayGateMask method
• nodetypes: added closestPolygon keyword arg to getUVAtPoint
• uitypes: added toPySide* functions for casting maya UI strings to PySide objects
• pymel.conf: added option to source initialPlugins.mel
• pymel.conf: added option to prefer PyQt4 or PySide
• util.arguments: added support for sets, useChangedKeys to compareCascadingDicts
• util.common: added inMaya() func
• stubs: make stub Mel.__getattr__ accept anything
• stubs: added PySide stubs

Bugfixes¶

• system: fixed bug with referenceQuery which occured when editStrings and liveEdits flags are True
• system: fixed bug with ReferenceEdit.remove() where self.rawEditData was referred to as a method instead of a property.
• ipymel: pressing ctrl-c no longer quits maya
• logging: fixed bug preventing logging menus from displaying

Non-Backward Compatible Changes¶

• joint.limitSwitchX/Y/Z: now return [bool, bool] when queried, just like the mel command, to indicate whether the limit is on for the min/max
• joint.radius: now returns the float radius, instead of [radius]

Changes¶

• general: addAttr/setEnums now accept strings, lists, or dicts for setting enums
• other: cast NameParser arguments to unicode
• factories: issue deprecation warning for deprecated functions only when they’re actually used

Additions¶

• added (functional) namespace method to Attribute, Component
• general: added mute accessors to Attributes
• system: provide ReferenceEdit.rawEditData property for getting faster unparsed access to reference edits
• nodetypes: added stripUnderworld flag to DependNode.nodeName(), and default it to true. This removes the underworld prefix (the node prior to ->) from nodeName().
• ipymel: update for ipython 0.11
• util.arguments: compareCascadingDicts can show which keys have been added (as opposed to just changed)
• system: added workspace.expandName

Bugfixes¶

• general: for the keyframe command, the upper / lower limits substituted in for the “index” flag, when no upper/lower limits were given, are now correct; formerly, the behavior of index=”:” would vary depending on where (in time) the first and last keyframes were
• general: timerange flags (ie, keyframe(time=...), findKeyframe(time=...), etc) now provide correct results when no upper/lower limits given; formerly, the time=”:” would vary depending on if / which objects were selected
• animation: Joint.angleX/Y/Z and Joint.stiffnessX/Y/Z now work
• nodetypes: Container.getParentContainer, Container.getRootTransform, and Character.getClipScheduler now all return None instead of raising a runtime error if no object was found
• system: FileReference.fullNamespace and iterReferences/listReferences with namespaces=1 now handle situations where reference node itself is in a non-root namespace correctly
• general: when instantiating PyNode from an MPlug, to get the PyNode for the node, create from the underlying mobject, not the name (which may not be unique)
• animation: fix for Joint.getAngleX/Y/Z, .getStiffnessX/Y/Z; joint.radius no longer returns list
• mel2py: numerous fixes / tweaks
• system: handle situations where reference node itself is in a non-root namespace
• system: FileReference.nodes fix when reference contains no nodes
• general: duplicate - special-case workaround for duplicating a single underworld node with no children
• general: fix for duplicate + non-unique names
• general: duplicate - workaround for bug introduced in 2014
• nodetypes: fix for getAllParents with underworld nodes
• Upgrade path.py to version 5.0 from github (https://github.com/jaraco/path.py). This fixes an issue with Maya2014, python 2.7.3, and Windows where path().isdir() raised an error.
• general: cmds.group returns unique name in maya > 2014
• fix for virtual classes
• versions: parsing for ‘Preview Release’ format - from Dean Edmonds

Non-Backward Compatible Changes¶

• DagNode.isVisible: has a new flag, checkOverride, which is on by default, and considers visibility override settings
• referenceQuery/FileReference.getReferenceEdits: if only one of successfulEdits/failedEdits is given, and it is false, we now assume that the desire is to return the other type (and set that flag to true); formerly, this would result in NO edits being returned
• parent no longer raises an error if setting an object’s parent to it’s current parent; this makes it behave similarly to the mel command, and to DagNode.setParent
• renameFile now automatically sets the ‘type’ if none is supplied (helps avoid renaming a file to ‘foo.ma’, then saving it as ‘mayaBinary’)
• general: 1D components have index() method: can no longer use string.index()
• uitypes: make PyUI.parent return None instead of PyUI(‘’)

Changes¶

• for maya versions >= 2012, creation of “ghost” plugin nodes no longer needed
• general: change to Component to speed up len(PyNode(‘pCube1Shape’).vtx)
• general: parent and DagNode.setParent now share common codebase
• general: when find unknown component type, default to just printing a warning and returning generic Component
• general: demoted raiseLog warning about unknown component type to DEBUG
• general: added uniqueObjExists function
• general: speedup for string representation of complete MeshVertexFace
• general: made listRelatives/listHistory/listConnections have same behavior for None and empty list
• system: clarified doc not about removeReferenceEdits not erroring
• system: FileReference.replaceWith - enable kwargs
• system: renameFile automatically sets type
• system: changed referenceQuery so when only one of successful/failed passed, other flag is opposite value
• language: make catch take args/kwargs
• nodetypes: attrDefaults - use MNodeClass in versions >= 2012, _GhostObjMaker otherwise
• nodetypes: Transform.setRotation now takes args as EulerRotation, Quaternion, or iterable of 3 or 4 elements
• nodetypes: isVisible checks overrideVisibility
• stubs: catch more dict-like-objects; special case exclude for maya.precomp.precompmodule
• stubs: create dummy data objects when safe; better handling of builtins
• stubs: use static code analysis to decide whether to include a child module in a parent module’s namespace
• stubs: better representations for builtin data types
• stubs: get all names in module, better ‘import *‘ detection
• plogging: added raiseLog func/method
• plogging: small tweaks to way default ERRORLEVEL is set, and raiseLog is added onto loggers
• ipymel: make sure stuff imported into global namespace in userSetup.py is available in IPython

Additions¶

• nodetypes: added stripNamespace option to DependNode.name
• general: disconnectAttr - support for disconnecting only certain directions
• general: MeshFace - added numVertices as alias for polygonVertexCount
• general: added DiscreteComponent.totalSize method
• general: added ParticleComponent class
• other: added DependNodeName.nodeName (for compatibility with DagNodeName)
• nodetypes: added DagNode.listComp
• datatypes: added equivalentSpace
• utilitytypes: proxyClass - added module kwarg to control __module__
• system: added FileReference.parent()
• system: listReferences - added loaded/unloaded kwargs
• system: added UndoChunk context manager
• system: Namespace.remove/.clean - added reparentOtherChildren kwarg
• system: added support for regexps to path.listdir/.files/.dirs
• system: added successful/failedEdits flags to FileReference.removeReferenceEdits
• windows: confirmBox - added returnButton kwarg to force return of button label
• plugins: added an example for creating plugin nodes
• util.enum: added Enum.__eq__/__ne__
• py2mel: added include/excludeFlagArgs
• system: added proper hash function for FileReference

Bugfixes¶

• general: fix for potential crashes due to using cached/invalid MFn
• general: fix pm.PyNode(‘pCube1.vtx[*]’)[2] to work like like pm.PyNode(‘pCube1’).vtx[2]
• general: fix for HashableSlice comparison (fixes bug with component indexing)
• general: Component - fixes for complete-component shortcut don’t use with empty meshes don’t use for subd components (including SubdUV) use ffd1LatticeShape.pt[*], not .pt[*][*][*]
• general: SubdEdge - hack to avoid a maya bug which causes crash
• language: MelGlobal.initVar now initializes in mel
• language: remove annoying callback error spam; instead make info available in a log from Callback.printRecentError()
• uitypes: fix for 2012 SP2 issue with objectTypeUI not working for windows with menu bars
• nodetypes: Transform.setRotation - fix for setting with EulerRotation object and non-standard rotation order or unit
• nodetypes: fix for ObjectSet.__len__
• nodetypes: AnimLayer.getAttribute - query dagSetMembers.inputs() to get full/unique path
• nodetypes: fix typo in name of NurbsCurve/Surface.controlVerts (not conrolVerts)
• core: _pluginLoaded - added fix for addPluginPyNodes triggered on reference load (fix for 2012+ only)
• core: fix erroneous ‘could not find callback id’ warnings
• utilitytypes: universalmethod now has doc pulled from original func
• util.conditions: bugfix for __ror__, added __str__
• allapi: toApiObject - low-level fix for Nucleus attributes
• startup: don’t use fixMayapy2011SegFault in >= 2013, seg fault was addressed by Autodesk
• stubs: fixes for objects with multiple aliases in a module
• py2mel: bugfixes, bugfix for excludeFlagArgs

Changes¶

• core.uitypes: improved AETemplates to work when created from within a scripted plugin
• tools.mel2py: now output exact same filename as input on Windows
• core.nodetypes: Transform.getRotation - can get as euler or quaternion
• extras: improved reliability of stub files (for pydev, wing, etc)
• core: doing select([], replace=True) should clear selection
• api.allapi: replace toMObjectName with MObjectName
• core: namespace - root option is now False (for backward compatibility)
• core: MeshVertex.setColors - set colors for all verts in MeshVertex
• core: re-implement noIntermediate flag to listRelatives
• plogging: PYMEL_LOGLEVEL env var now sets minimum level for all pymel loggers
• core: use new 2012 pluginInfo flags for getting more command types
• core.windows: PopupError can now raise another exception type
• examples: update customClasses.py example

Additions¶

• util.path: added boolean normcase keyword arg to path.canonicalpath()
• api.plugins: added in classes for all MPxNode classes and methods for querying class / MPx to MPx enum mappings
• api.plugins: added new overridable methods which generate node callbacks: timeChagned, forcedUpdate, nodeAdded, nodeRemoved, preConnectionMade
• versions: added maya2012 hotfix 1,2,3,4
• core: Attribute.setDirty / evaluate
• core: DependNode.rename() now supports pyMel unique flag preserveNamespace
• core: added check to ensure name passed to DependNode.rename() is shortname
• core: implemented DependNode.rename() flags: i.e. ignoreShape can now be used
• core.uitypes: added Layout.findChild() which takes the shortname of a child as a string and returns the PyUI object

Bugfixes¶

• mayautils: fix so recurseMayaScriptPath, when given explicit roots, doesn’t wipe out old paths
• core: fixed bug where __pymelUndoNode was created in non root namespace
• tools.pymelScrollFieldReporter: use mel2py.melparse (issue 247)
• core: fixed FileReference.importContents(removeNamespace=True)
• core: _pluginLoaded callback now correctly triggered by importing
• core: fix promptForPath doesn’t work for mode 1/100 due to testing for the existance of the path.
• core.nodetypes: fix for DependNode.rename(preserveNamespace=True) when node in root namespace
• core.nodetypes: fixed bug with RenderLayer.added/removeAdjustments
• core.nodetypes: fix for DagNode.getAllParents (and test)
• core.nodetypes: fix for DependNode.hasAttr(checkShape=False)
• core.nodetypes: fix for AnimCurve.addKeys (issue 234)
• internal.startup: fix for error message when fail to import maya.cmds.about
• core: fixed addAttr(q=1, dataType=1) so it does not error if non-dynamic attr
• core: pythonToMelCmd - fixed bug when flagInfo[‘args’] was not a class
• core: pythonToMelCmd - fix for flags where numArgs > 1
• maya.utils: formatGuiException - fix for, ie, IOError / OSError
• updated 2012 caches to fix issue 243

Changes¶

• UI classes that have ‘with’ statement support now set parent back to previous ‘with’ object if there are nested with statements; if not in a nested with statement, resets parent back to UI element’s parent (or more precisely, the first element that is not a rowGroupLayout element)

• with OptionMenuGrp() will set parent menu properly

• ‘Unit’ support for Quaternion objects is now removed (as it doesn’t make any sense)

• can now pass in PyNode class objects to functions / methods that expect a mel node class name - ie:

  listRelatives(allDescendents=True, type=nt.Joint)

  is equivalent to:

  listRelatives(allDescendents=True, type=’joint’)

• other: NameParser(dagObj) now always gives a DagNodeName even if shortName has no |

Non-Backward Compatible Changes¶

• PyNode(‘*’) - or any other non-unique name - now returns an error use ls(‘*’) if you wish to return a list of possible nodes
• By default, the root pymel logger outputs to sys.__stdout__ now, instead of sys.stderr; can be overriden to another stream in sys (ie, stdout, stderr, __stderr__, __stdout__) by setting the MAYA_SHELL_LOGGER_STREAM environment variable
• skinCluster, tangentConstraint, poleVectorConstraint, and pointOnPolyConstraint commands now return a PyNode when creating, instead of a list with one item
• skinCluster command / node’s methods / flags for querying deformerTools, influence, weightedInfluence now return PyNodes, not strings
• Attribute.elements now returns an empty list instead of None
• general: Attribute.affects/affected return empty list when affects returns None
• setParent returns PyUI / None; menu(itemArray) returns [] for None
• general: make Attribute.elements() return empty list for None
• shape attribute lookup on all child shapes (like mel does)

Additions¶

• Shape.setParent automatically adds –shape flag
• nodetypes: added isVisible
• added MGlobal.display* methods to pymel.core.system namespace
• other: added NameParser.stripGivenNamespace()
• language: OptionVarList has more helpful error message when __setitem__ attempted
• nodetypes: getSiblings can now take kwargs
• Added MainProgressBar context manager
• Added isUsedAsColor method to Attribute class
• Added wrapper for listSets function
• Added method listSets to PyNode class
• Added a folderButtonGrp
• system: added Namespace.move
• system: added Namespace.listNodes
• mel2py: python mel command now translated to pymel.python (ie, maya.cmds.python)
• general: added Attribute.indexMatters
• language: added animStart/EndTime to Env
• system: added in a ‘breadth’-first recursive search mode to iterReferences
• general: added ability to set enum Attributes with string values (issue 35)
• plogging: set logging level with PYMEL_LOGLEVEL env var
• Added isRenderable() method to object set.
• deprecate PyNode.__getitem__
• mayautils: executeDeferred now takes args, like maya.utils.executeDeferred

Bugfixes¶

• py2mel failing with functions that take *args/**kwargs
• eliminated / fixed various ‘warning’ messages on pymel startup
• MayaNodeError / MayaAttributeError not being raised when a node / attribute not found
• some maya cmds were not handling ‘stubFunc’ correctly
• renderLayer.listAdjustments() was not functioning
• MainProgressBar fixed
• language: OptionVarList __init__ no longer raises deprecation warning
• listSets() throws away non-existant ‘defaultCreaseDataSet’ that maya.cmds.listSets() returns
• fix for dealing with maya bug where constraint angle offsets always returned in radians (but set in degrees)
• fixes for incorrect formatting of error strings in some cases
• fixes for unloading of commands/nodetypes when plugins unloaded (and pymel.all was imported first)
• miscellaneous documentation fixes
• fix for mayautils.executeDeferred when invoked with args
• fix for Attribute.getAllParents()
• fix for aliased multi/compound attributes
• fix for Attribute.isSettable with multi/compound attributes
• fix for Attribute.exists with multi/compound attributes
• fix for Attribute.type with multi/compound attributes dynamic attributes
• fix for published container node attributes / aliases
• fixes for plugin callback failing when plugin has uncreate-able nodes
• fixes for multiple iterators of a mutli-attribute not being independent
• fix for MeshVertex.setColor
• fix for MeshVertex.isConnectedTo
• fix for MeshVertex.getColor
• fix for MeshEdge.isConnectedTo
• fix for MeshFace.isConnectedTo
• fix for plogging handling case where various env. variables exist, but are empty
• Fix for Layout.children() Layout.children() now returns empty list if layout has no kids intead of raising error.
• listConnections: fix so rotatePivot always Attribute (not component)
• uitypes: bugfixes to AETemplates. corrected UITemplate to represent an existing uiTemplate if instantiated with the name of an existing template
• nodetypes: fixed a bug where Transform.setScalePivot was internally using MFnTransform.setScalePivotTranslation
• fixed a bug in pythonToMel where python booleans were not converted to integer. this caused the Mel class to not work properly with booleans.
• core.general: fix a bug with sets command where noWarnings was interpreted as a set flag, instead of a boolean flag
• Namespace: fix for getParent()
• general: various attr name fixes (stripping of [-1] indices, etc)
• nameparse: enable parsing of [-1] indices (for attributes)
• nodetypes: enable parsing of [-1] indices (for attributes)
• nodetypes: setParent to current parent no longer errors
• util.enum: fix for repr of EnumDict
• fixes for referenceQuery
• attr.exists() should return False if the node no longer exists
• datatypes: fixed bug to allow Point * FloatMatrix
• general: bugfix for Attribute.attrName
• utilitytypes: EquivalencePairs.get now correctly retrieves value=>key
• nodetypes: fixed setParent(world=1) bug
• uitypes: Fix issues with the popup and with support.
• pm.mel.command translation would fail with no-arg bool flags (like -q, -e)
• language: mel command translation makes no assumptions for unknown commands; None is translated to empty string, not ‘None’
• bugfix for uiTemplate(exists=1)
• general: Attribute.elements() now correctly works with array and element plugs
• fix get/set rotation by using eulerRotation
• startup: changes to fix issues with maya -prompt and plugins loading pymel
• fix for TransformationMatrix.get/setRotation, removed Quaternion units
• datatypes: fixes for EulerRotation
• fix for ui heights for pymelControlPanel
• uitypes: bugfix for with statement parent setting on exit
• mesh: fixes to allow creating component objects for empty meshes (ie, createNode(‘mesh’).vtx)
• mesh: made more num* functions work with empty meshes
• core.general: fix for move with no object
• datatypes: fix for EulerRotation comparison/len
• fix for menu(‘someOptionMenu’)
• FileReference: initialize correctly from a path
• windows: bugfix - informBox wasn’t using ‘ok’ kwarg
• plogging: bugfix for 182 - crash due to creating loggers as iterating over dict
• arrays: fix for dot/outer product error messages (issue 158)
• fix for ‘no useName’ and MfknSkinCluster.setBlendWeights warnings on startup
• Fixed language import in MainProgressBar
• fix for Issue 216: renderLayer.listAdjustments()
• docfix for issue 192
• fix for constraint angle offset query always being in radians
• nodetypes: fix for multi/compound alias attrs
• nodetypes: fixes for published container node attributes / aliases
• general: made attribute iterator independent
• general: fix for isSettable with multi/compound attributes
• general: fix so getAllParents doesn’t return orig object
• general: fix for Attribute.exists with multi/compound attrs
• Attribute.type() now works with multi/compound, dynamic attrs
• fixes for mesh components

Changes¶

• rolled back listConnections() change from 1.0.1

Additions¶

• added functions for converting strings to PyQt objects: toQtObject(), toQtLayout(), toQtControl(), toQtMenuItem(), toQtWindow()
• added method for converting PyMEL UI objects to PyQt objects: UI.asQtObject()

Bugfixes¶

• fixed a bug where nt.Conditions() created a script condition

Changes¶

• listConnections: when destination is shape, always returns shape (not transform)
• select([]) only clears selection if mode is replace
• deprecated Attribute.firstParent()

Additions¶

• mel2py: now does packages/subpackages for recursed mel subdirectories
• added various dict-like methods to OptionVarDict
• added new EnumDict support which Attribute.getEnum returns
• added support to getAttr() / Attribute.get() for getting message attributes, which are returned as DependNodes
• added core.system.saveFile()
• added pymel.versions.is64bit()
• added new directory helpers to mayautils: getMayaAppDir(), getUserPrefsDir(), and getUserScriptsDir()
• added DependNode.longName(), DependNode.shortName(), and DependNode.nodeName() for easy looping through mixed lists of DependNodes and DagNodes
• added FileInfo.__delitem__()
• added DependNode.deleteAttr()

Bugfixes¶

• unloading plugins no longer raises an error
• python AE templates were not being found. fixed.
• fixed a bug in api wrap, where MScriptUtil was not allocating space
• fixed a bug with Transform.setMatrix()
• pymel.versions.installName() is more reliable on 64-bit systems, which were sometimes detecting the installName incorrectly
• Attribute('mytransform.scalePivot') now returns an the scalePivot attribute
• getAttr() / Attribute.get() bugfix with multi-attr
• nodetypes: fixed bug 172 where nested selection sets were raising an error when getting members
• getPanel now always return panels
• uitypes: all panel classes now properly inherit from Panel
• fixed some keywords that had been mistakenly refactored
• core.general: fixed a bug where dependNodes were not returned when duplicated

Non-Backward Compatible Changes¶

• pymel no longer has ‘everything’ in namespace - use pymel.all for this
• pymel.core.nodetypes now moved to it’s own namespace
• pymel.mayahook.Version functionality moved to pymel.versions module. to compare versions, instead of Version class, use, for example, pymel.versions.current() >= pymel.versions.v2008
• pymel.mayahook.mayautils.getMayaVersion() / getMayaVersion(extension=True) replaced with pymel.versions.installName()
• pymel.mayahook.mayautils.getMayaVersion(extension=True) replaced with pymel.versions.shortName()
• removed 0_7_compatibility_mode
• removed deprecated and inapplicable string methods from , base of all PyNodes:
• removed Smart Layout Creator in favor of ‘with’ statement support
• DagNode.getParent() no longer accepts keyword arguments
• Renamed UI base class to PyUI
• sceneName() now returns a Path class for an empty string when the scene is untitled. this makes it conform more to cmds.file(q=1, sceneName=1)
• replaced listNamespace with listNamespace_new from 0.9 line

Features¶

• added support for creation of class-based python Attribute Editor templates, using ui.AETemplate
• added ‘with statement’ compatibility to UI Layout and Menu classes
• added the ability to generate completion files for IDEs like Wing, Eclipse, and Komodo

Tools¶

• ipymel: added colorization to dag command
• py2mel: now works with lambdas and methods. new option to provide a list or dictionary of mel types.
• re-added missing scriptEditor files
• added upgradeScripts, a tool for converting 0.9 scripts to be 1.0 compatible

Changes¶

• moved functions for working with the shell into util.shell
• split out ui classes from core.windows into core.uitypes for lazy loading
• for versions >= 2009, use open/close undo chunks instead of mel hack to ensure that an entire callback can be undone in one go
• improved lsUI()
• moved component types out of nodetypes and into general
• __repr__ for nodetypes, uitypes, and datatypes reflect their location so as not to cause confusion. using short module names nt, ui, and dt.
• caches are now compressed for speed
• allow setting pymel.conf location via environment variable PYMEL_CONF
• DagNode.getBoundingBox() now allows you to specify space
• ensured that the ‘name’ flag for surface and curve operates on shape as well
• changes to allow myCube.vtx[1,3,5]
• commands wrapped by pmcmds that raise a standard TypeError for a non-existent object will now raise a MayaObjectError
• simplified getParent code on Attribute and DagNode to improve function signatures.
• fixed a bug with ls(editable=1)
• fixed a bug with ObjectSets containing DagNodes
• callbacks: extra debug information is printed in tracebacks

Additions¶

• added TwoWayDict/EquivalencePair to utilitytypes
• added preorder(), postorder(), and``breadth()`` functions in util.arguments, which have more intuitive arguments
• added new Layout class that all layouts inherit from
• added UITemplate class
• added usable __iter__ to workspace dict / file dict objects
• added two tier setup scripts for maya (user/site) just like with python. This new siteSetup.py is intended for studio setup of maya and reserved userSetup.py for user level scripts.
• added a partial replacement maya package with a logger with a shell and gui handler qne changed plogging to use the new default maya logger
• added setAttr/getAttr support for all numeric datatypes, along with tests
• added Transform.getShapes() for returning a list of shapes
• added FileReference comparison operators
• added DependNode.longName(stripNamespace=False,level=0)
• added SkinCluster.setWeights()
• added AnimCurve.addKeys()
• added regex flag to ls command
• added FileInfo.get()
• added util.common.subpackages() function for walking package modules
• added util.conditions.Condition class for creating object-oriented condition testing
• pymel.conf: added a fileLogger
• added Path.canonicalpath() and Path.samepath()
• mel2py: added command-line flags, ability to recurse

Bugfixes¶

• fixed instantiation of PyNode from MPlug instance
• fixed a bug where Maya version was incorrectly detected when Maya was installed to a custom location
• fixed bug where wrap of function which took multiple refs all pointed to same MScriptUtil
• fixed wrapping of unsigned ptr api types
• fixed negative comp indices
• mel2py: bugfix with mel2pyStr()

Changes and Additions¶

• added support for 2010 and python 2.6
• added basic support for all component types
• added a ‘removeNamespace’ flag to FileReference.importContents()
• added support for open-ended time ranges for command like keyframes (Issue 82)
• enhanced keyframe function: if both valueChange and timeChange are queried, the result will be a list of (time,value) pairs
• added ability to pass a list of types to ls ‘type’ argument, as you can with listRelatives
• added checkLocalArray and checkOtherArray arguments to Attribute.isConnectedTo which will cause the function to also test mulit/array elements
• improved core.language.pythonToMel() reliability on lists
• improved custom virtual class workflow
• added functionality to pymel.tools.py2mel for dynamically creating MEL commands based on python functions/classes
• added a new module pymel.api.plugins for working with api plugins in a more reasonable and automated fashion
• updated eclipse integration documentation

Bugfixes¶

• importFile(), createReference(), loadReference(), and openFile() now return PyNodes when passed returnNewNodes flag (Issue 85)
• fixed rare bug with Vista where platform.system was failing during startup (Issue 87)
• fixed a bug with plugin loading to intelligently handle when callback does not get a name
• fixed optionMenu and optionMenuGrp to return empty lists instead of None
• restored core.other.AttributeName.exists() method
• fixed a bug in 0.7_compatibility_mode
• fixed minor bug in listRelatives()
• fixed a bug where curve command was returning a string instead of a PyNode (Issue 96)

Changes and Additions¶

• new feature: virtual subclasses. allows the user to create their own subclasses which are returned by PyNode
• added v2009sp1 and v2009sp1a to Version
• changed MelGlobals.__getitem__ to raise a KeyError on missing global, instead of a typeError
• util.path now supports regular expression filtering in addition to globs.
• moved moduleDir() from util to mayahook since it is explicitly for pymel.
• ensured that all default plugins are loaded when creating the api cache so that we can avoid calculating those each time the plugins are loaded
• added a new errors flag to recurseMayaScriptPath for controlling how to handle directory walking errors: warn or ignore
• moved pwarnings to ensure that pymel.util is completely separated from maya
• adding new sphinx documentation. modifying source docstrings where necessary.
• setParent now allows None arg to specify world parent
• adopted a standard setuptools-compliant package layout, with pymel as a subdirectory of the top level
• forced line numbers on for Mel.eval
• changed ipymel to use $MAYA_LOCATION to find mayapy instead of /usr/bin/env
• changed datatypes examples to demonstrate the necessity to include a namespace
• added groupname, get_groupname, and chgrp to Path class for dealing with unix groups as strings instead of as gid’s
• added alias path.Path for path.path so as to follow PEP8
• added a new option to pymel.conf to allow disabling of mel initialization in standalone mode.
• added ability to set logger verbosity using PYMEL_LOGLEVEL environment variable. great for quick testing.

Bugfixes¶

• fixed a bug in undoInfo()
• fixed a bug that was breaking mel2py
• fixed a bug with logging that was locking it to INFO level. INFO is now the default, but it can be properly changed in pymel.conf
• fixed input casting of datatypes.Time
• bug fixes in error handling within path class
• fixed issue 65: DependencyNode.listAttr() broken
• made sure NameParse objects are stringified before fed to MFnDependencyNode.findPlug()
• added a few more reserved types so as to avoid creating them, which can lead to crashes on some setups
• fixed issue 66 where nodes could be created twice when using PEP8 style class instantiation: pm.Locator
• path.walk* methods now properly prune all directories below those that do not match the supplied patterns
• maya bug workaround: changed pluginLoaded callback to API-based for 2009 and later
• fixed bug in hasAttr()
• removed bug in arrays.dot where incorrect duplicate definition was taking precedence
• fixed bug in PyNode.__ne__() when comparing DagNodes to DependNodes
• fixed Issue 72: cannot select lists of components
• fixed bug with startup on windows (backslashes not escaped)
• fix for Component('pCube1.vtx[3]')
• fix for nurbsCurveCV(‘nurbsCircle1’) failing
• pythonToMel and Mel now properly convert datatypes.Vectors to mel vectors ( <<0,0,0>> ). MelGlobals now returns datatypes.Vectors
• fixed bug with duplicate(addShape=1)
• fixed a bug where selectionSets can’t be selected
• fixed a bug with sets() when it returns lists
• fixed issue 76, where non-unique joint names were returned by pymel.joint and thus were unsuccessfully cast to nodetypes.Joint
• fixed issue 80, regading incorrect association of nodetypes.File with cmds.file.
• fixed a bug in connectAttr() that was preventing connection errors from being raised when the force flag was used

Easy Install¶

As of version 0.9.1 PyMEL supports installation via setuptools, which makes it a lot easier to get started if you’re not well-versed in the intricacies of the PYTHONPATH. If you don’t already have setuptools installed it will be downloaded for you when you run the install command below, but in order for this to all go smoothly you must have the following things:

• a connection to the internet
• write permission to your Maya installation directory

If you fall short on either of these you can always perform a Manual Install of PyMEL.

Manual Install¶

If the easy install did not turn out to be so easy, PyMEL can always be manually installed like any other python module or package. The process is simple in concept:

1. put the extracted pymel folder somewhere
2. tell python where to find it

To find available modules, python searches directories set in an environment variable called PYTHONPATH. This environment variable can be set for each Maya installation using the Maya.env file, or it can be set at the system level, which will set it for all instances of python, including those bundled with each Maya installation (aka “mayapy”).

export MAYA_LOCATION=/Applications/Autodesk/maya2009/Maya.app/Contents
export PATH=$MAYA_LOCATION/bin:$PATH
export PYTHONPATH=/path/to/pymel-1.0.0

ipymel Easy Install¶

As of version 0.9.2 ipymel is automatically installed when “easy” installing PyMEL, but you may have to do a few extra steps to get it working properly on Windows.

Windows Only:

• Install python on your system. Install only the exact versions of python that come with Maya ( see `Versions of Maya and Python`_ )
• Install pyreadline for windows from the IPython website. By default it will install to your system copy of Python.
• Copy the pyreadline directory, and all the pyreadline.* files from your system site-packages directory ( ex. C:\Python25\Lib\site-packages ) to your Maya site-packages directory ( ex. C:\Program Files\Autodesk\Maya2008\Python\lib\site-packages ).

To Run: In a new shell, run the following command:

ipymel

ipymel Manual Install¶

Linux¶

If you encounter an error installing on linux, you may have to fix a few symlinks. Here’s how you check. cd to the directory where you unzipped pymel (you should be in the same directory where setup.py is). start up maya’s standalone interpreter by typing mayapy (or provide the full path to mayapy script if you do not have Maya’s bin directory on your PATH) at the prompt. now import setup.py as a module and run one of it’s tests:

import setup
setup.test_dynload_modules()

This will print out any compiled modules that do not work on your platform. This occurs because the flavor and/or distribution of Linux that you are running has different versions of certain system libraries than the one that Maya was compiled on. The easiest way to fix the problem is to create symbolic links from your existing libraries to those that Maya expects to find.

For example, in my case hashlib won’t import because it can’t find libssl.so.4. So, since I’m on a 64-bit version of linux, I check my /lib64/ ( on a 32 bit OS, check /lib/ )

cd /lib64
ls -la libssl*

I see the following returned:

-rwxr-xr-x 1 root root 302552 Nov 30  2006 libssl.so.0.9.8b
lrwxrwxrwx 1 root root     16 Jul 16  2007 libssl.so.6 -> libssl.so.0.9.8b

In my case, Maya expects libssl.so.4, but instead I have libssl.so.0.9.8b and a symbolic link libssl.so.6 pointing to libssl.so.0.9.8b. So, I have to create a symbolic link from the real library to the missing library:

sudo ln -s libssl.so.0.9.8b libssl.so.4

I’ve found that the same thing must sometimes be done for libcrypto as well.

Importing PyMEL¶

To get started we need to import the pymel module:

from pymel.core import *

This brings everything in pymel into the main namespace, meaning that you won’t have to prefix the maya commands with the module name.

from pymel.core import *
s = sphere() # create a nurbsSphere
sphere = 'mySphere'  # oops, we've overwritten the sphere command with a string
sphere()
# Error: name 'sphere' is not defined
# Traceback (most recent call last):
#   File "<maya console>", line 1, in <module>
# NameError: name 'sphere' is not defined #

An Intro to PyMEL Objects in Maya¶

Before we proceed let’s make sure we have a clean scene so that you’ll get the same results as me:

f=newFile(f=1) #start clean

Let’s start by listing the cameras in the scene. We do this in the same way that we would with maya.cmds:

ls(type='camera')
# Result: [nt.Camera(u'frontShape'), nt.Camera(u'perspShape'), nt.Camera(u'sideShape'), nt.Camera(u'topShape')]

Just for comparison, let’s do the same thing using maya.cmds:

import maya.cmds as cmds
cmds.ls(type='camera')
# Result: [u'frontShape', u'perspShape', u'sideShape', u'topShape']

Notice the difference in the returned results. In the second example using maya.cmds, the ls function returns a list of strings. For those of us coming from a MEL background, a list of names as strings is what we would expect out of ls. PyMEL returns something much better – instances of PyNode classes – which are like strings on steroids. In addition to methods for operating on node names as strings, these classes have methods for operating on the type of node or UI element that the string represents.

Let’s use one of these camera objects to get some information. To do this using maya.cmds we might write something like this:

cam = ls(type='camera')[0]
camera( cam, query=True, aspectRatio=True)
# Result: 1.5
camera( cam, query=True, focalLength=True)
# Result: 35.0
camera( cam, edit=True, focalLength=20)

Rewriting this in an object-oriented way is fairly straight-forward:

cam = ls(type='camera')[0]
cam.getAspectRatio()
# Result: 1.5
cam.getFocalLength()
# Result: 35.0
cam.setFocalLength(20)

The two examples start out the same way: with the ls function. This is how we get our raw material to work with, in this case our node objects. In general, we can get nodes in 3 ways:

• list them based on some criteria
• create them
• get them by their name if we know it

Once we have our list of nodes, we can begin to work in an object-oriented fashion. There is not a hard-fast rule for converting from a procedural style to an object-oriented one, but here are some general guidelines:

• the argument to the command – in this case cam – becomes the operating object on the left
• instead of flags – focalLength and aspectRatio we use methods, which are attached to right of the object with a period .
• query methods are typically prefixed with ‘get’ and edit methods are prefixed with ‘set’. If a query does not have a corresponding edit, it may not have a ‘get’ prefix.

So, in our case query=True, aspectRatio=True becomes .getAspectRatio. And query=True, focalLength=True becomes .getFocalLength.

Getting Help¶

If you are ever unsure of what method to use, just use the builtin python help command on the node class (the capitalized node type). First find out what type of node you’re working with. we’ll continue from the example above, with our cam variable:

print repr(cam)

This prints nt.Camera(u'frontShape'). The nt.Camera part tells you what type of object it is. Now we can get help on that object type:

help(nt.Camera)

This prints all the documentation on the Camera node type. If you want help on a particular method, you can do this:

help(nt.Camera.getFocalLength)

You can do the same thing for any function as well:

help(ls)

Attributes¶

I think it’s time we learned how to set some attributes. Let’s go back and take a look at our plane’s transform and access an Attribute object. Just like nodes, attributes have their own class with methods that encompass the dozens of MEL commands for operating on them.:

print `plane.translateX`
# Result: Attribute(u'pPlane1.translateX')

To get and set attributes:

plane.translateX.get()
# Result: 0.0
plane.translateX.set(10.0)

Here’s a few examples of how to query and edit properties of attributes:

plane.translateX.isLocked()
# Result: False
plane.translateX.setLocked(True)
plane.translateX.isKeyable()
# Result: True
plane.translateX.setKeyable(False)

Connections¶

Now let’s look into getting other objects connected to our plane shape. The Attribute.connections method accepts the same flags as the procedural command listConnections.

Below we get incoming and outgoing connections:

shape.connections()
# Result: [ShadingEngine(u'initialShadingGroup'), PolyPlane(u'polyPlane1')]

inputs is a shorcut to connections(source=True):

shape.inputs()
# Result: [PolyPlane(u'polyPlane1')]

outputs is a shorcut to connections(source=False):

shape.outputs()
# Result: [ShadingEngine(u'initialShadingGroup')]

Notice that when we enable the plugs flag that the result becomes an Attribute instead of a node type.:

shape.inputs(plugs=1)
# Result: [Attribute(u'polyPlane1.output')]

Here’s another handy feature of python: it supports 2D arrays, meaning you can put lists inside lists. PyMEL takes advantage of that in many situations, including when we enable the connections flag, which causes listConnections to list source-destination pairs.:

shape.connections(c=1, p=1)
# Result: [(Attribute(u'pPlaneShape1.instObjGroups[0]'), Attribute(u'initialShadingGroup.dagSetMembers[0]')), (Attribute(u'pPlaneShape1.inMesh'), Attribute(u'polyPlane1.output'))]

This is particularly useful for looping

for source, destination in shape.connections(c=1, p=1):
...     print source, destination

pPlaneShape1.instObjGroups[0] initialShadingGroup.dagSetMembers[0]
pPlaneShape1.inMesh polyPlane1.output

Using Existing Objects by Name¶

In many cases, you won’t be creating objects directly in your code, but will want to gain access to an existing object by name. PyMEL provides two ways of doing this. Both of them will automatically choose the correct PyMEL class for your object.

The PyNode class:

PyNode( 'defaultRenderGlobals').startFrame.get()
# Result: 1.0

The SCENE object ( an instance of the Scene class )

SCENE.defaultRenderGlobals.startFrame.get()
# Result: 1.0

Mel Scripts¶

Calling MEL scripts through maya.mel.eval is a nuisance because it requires so much string formatting on the programmer’s part. pymel.mel handles all of that for you so you can use your MEL scripts as if they were python functions. This includes automatically formatting all iterable types into maya arrays.

See out pymel.core.language.Mel for more information.

What to Change¶

All of the MEL functions in maya.cmds exist in pymel, with a few exceptions ( see Module Documentation ). MEL functions that operate on nodes and/or attributes almost always fall into one or more of these categories: creating, listing, querying/editing. As you begin shifting toward a more object-oriented approach, you will still retain the need for procedural programming. Use these guidelines for what aspects of PyMEL are best suited to object-oriented programming:

1. creating nodes and UI elements : remains mostly procedural
2. listing objects and UI elements: object-oriented, except for general listing commands like ls
3. querying and editing objects and UI elements: object-oriented, except for commands that operate on many nodes at once, like select and delete

Partial Conversion is Bad, mmkay¶

Mixing maya.cmds module with pymel.core will result in problems, because maya.cmds doesn’t know what to do with anything other than very basic data types. Passing a PyNode, Matrix, Vector, or other custom type to a maya.cmds function will result in errors. Your best bet is to completely replace maya.cmds with pymel throughout your code in one go. This might sound frightening, but it will ultimately lead to fewer errors than partial PyMEL integration. The purely procedural part of pymel.core will behave exactly the same as maya.cmds as long as it is replaced wholesale, but if it is not, results returned from PyMEL functions will cause errors when passed to maya.cmds functions, and results from maya.cmds will need to be cast to PyNodes.

There are only a handful of maya.cmds wraps in PyMEL that are not backward compatible. They all fall into the category of functions which now return a list of tuple pairs instead of a flat list:

listConnections( connections=True )
keyframe( q=True, valueChange=True )
keyframe( q=True, timeChange=True )
ls( showType=True )

These changes are all noted in the docstrings of each function.

Node Renaming¶

Maya nodes can be renamed, which means that each time the name of the node is required – such as printing, slicing, splitting, or passing to any command derived from maya.cmds – the object’s current name is queried from the underlying API object. This ensures renames performed via mel or the UI will always be reflected in the name returned by your PyNode class and your variables will remain valid despite these changes.:

>>> orig = polyCube(name='myCube')[0]
>>> print orig                    # print out the starting name
myCube
>>> orig.rename('crazyCube')      # rename it (the new name is returned)
Transform(u'crazyCube')
>>> print orig                    # the variable 'orig' reflects the name change
crazyCube

As you can see, you do not need to assign the result of a rename to a variable, although, for backward compatibility’s sake, we’ve ensured that you still can.

Querying the name of the object is not infinitely fast, so try to avoid doing it repetitively, if possible.

See Using PyNodes as Keys in Dictionaries for more information on PyNode mutability.

MEL Node Commands and their PyNode Counterparts¶

As you are probably aware, MEL contains a number of commands which are used to create, edit, and query object types in maya. Typically, the names of these commands correspond with the node type on which they operate. However, it should be noted that there are a handful of exceptions to this rule.

Some examples of command-class pairs. Notice that the last two nodes do not match their corresponding command:

This example demonstrates some basic principles. Note the relationship between the name of the object created, its node type, and its class type. Also notice that instead of creating new objects using maya.cmds functions ( ex. spotlight ), the class ( ex. nt.SpotLight ) can also be used :

>>> from pymel.core import *
>>> l = nodetypes.SpotLight()
>>> print "The name is", l
The name is spotLightShape1
>>> print "The maya type is", l.type()
The maya type is spotLight
>>> print "The python type is", type(l)
The python type is <class 'pymel.core.nodetypes.SpotLight'>

Once you have an instance of a PyMEL class, you can use it to query and edit the maya node it represents in an object-oriented way.

Make the light red and get shadow samples, the old, procedural way:

>>> spotLight(l, edit=1, rgb=[1, 0, 0])
>>> print spotLight(l, query=1, shadowSamples=1)
1

Now, the object-oriented, PyMEL way:

>>> l.setRgb([1, 0, 0])
>>> print l.getShadowSamples()
1

For those familiar with MEL, you can probably already tell that the DirectionalLight class can be understood as an object-oriented reorganization of the directionalLight command, where you ‘get’ queries and you ‘set’ edits.

Some classes have functionality that goes beyond their command counterpart. The nt.Camera class, for instance, also contains the abilities of the track, orbit, dolly, and cameraView commands:

>>> cam = nodetypes.Camera(name='newCam')
>>> cam.setFocalLength(100)
>>> cam.getHorizontalFieldOfView()
20.407947443463367
>>> cam.dolly(distance=-3)
>>> cam.track(left=10)
>>> cam.addBookmark('new')

API Classes and their PyNode Counterparts¶

PyNode classes derive their methods from both MEL and the API ( aka. maya.cmds and maya.OpenMaya, respectively ). If you’re familiar with Maya’s API, you know that there is a distinct separation between objects and their abilities. There are fundamental object types such as maya.OpenMaya.MObject and maya.OpenMaya.MDagPath that represent the object itself, and there are “function sets”, which are classes that, once instantiated with a given fundamental object, provide it with special abilities. ( Because I am a huge nerd, I like to the think of the function sets as robotic “mechs” and the fundamental objects as “spirits” or “ghosts” that inhabit them, like in Ghost in the Shell ).

For simplicity, PyMEL does away with this distinction: a PyNode instance is the equivalent of an activated API function set; the necessary fundamental API objects are determined behind the scenes at instantiation. You can access these by using the special methods nt.DependNode.__apimobject__, Attribute.__apimobject__, nt.DependNode.__apihandle__, nt.DagNode.__apimdagpath__, Attribute.__apimdagpath__, Attribute.__apimplug__, and PyNode.__apimfn__. (Be aware that this is still considered internal magic, and the names of these methods are subject to change ):

>>> p = PyNode('perspShape')
>>> p.__apimfn__() 
<maya.OpenMaya.MFnCamera; proxy of <Swig Object of type 'MFnCamera *' at ...> >
>>> p.__apimdagpath__() 
<maya.OpenMaya.MDagPath; proxy of <Swig Object of type 'MDagPath *' at ...> >
>>> a = p.focalLength
>>> a
Attribute(u'perspShape.focalLength')
>>> a.__apimplug__() 
<maya.OpenMaya.MPlug; proxy of <Swig Object of type 'MPlug *' at ...> >

As you can probably see, these methods are enormously useful when prototyping API plugins. Also of great use is the PyNode class, which can be instantiated using API objects.

attr Method¶

The attr method is the safest way to access an attribute, and can be used to access attributes that conflict with python methods and would therefore fail using shorthand syntax. This method is passed a string which is the name of the attribute to be accessed.

>>> cam.attr('visibility')
Attribute(u'persp.visibility')

Unlike the shorthand syntax below, this method is capable of being passed attributes as variables:

>>> for axis in ['scaleX', 'scaleY', 'scaleZ']:
...     cam.attr( axis ).lock()

Shorthand¶

The shorthand method is the most visually appealing and readable – you simply access the maya attribute as a normal python attribute – but it has one major drawback: if the attribute that you wish to acess has the same name as one of the attributes or methods of the python class then it will fail.

>>> cam  # continue from where we left off above
Transform(u'persp')
>>> cam.visibility # long name access
Attribute(u'persp.visibility')
>>> cam.v # short name access
Attribute(u'persp.visibility')

Keep in mind, that regardless of whether you use the long or short name of the attribute, you are accessing the same underlying API object.

If you need the attribute formatted as a string in a particular way, use Attribute.name, Attribute.longName, Attribute.shortName, Attribute.plugAttr, or Attribute.lastPlugAttr.

Direct Instantiation¶

The last way of getting an attribute is by directly instantiating the class with the full name of the attribute, including the node. You can pass the attribute name as a string, or if you have one handy, pass in an api MPlug object. If you have a name as a string, but you don’t know whether it represents a node or an attribute, you can always instantiate via the PyNode class, which will determine the appropriate class automatically.

explicitly request an Attribute:

>>> Attribute('persp.visibility')
Attribute(u'persp.visibility')

let PyNode figure it out for you:

>>> PyNode('persp.translate')
Attribute(u'persp.translate')

Function Name as String¶

The simplest method of setting up a callback is to pass the name of the callback function as a string. Maya will try to execute this as python code. Here’s a simple example:

from pymel.core import *

def buttonPressed():
    print "pressed!"

win = window(title="My Window")
layout = columnLayout()
btn = button( command='buttonPressed()' )

showWindow()

This example works fine if you run it from the script editor, but if you save it into a module, say myModule, and then import that module as normal ( e.g. import myModule ), it will cease to work (assuming you haven’t already run it from the script edtior). This is because the namespace of the buttonPressed function has changed. It can no longer be found as buttonPressed, because from Maya’s perspective, its new location is myModule.buttonPressed.

There are several solutions to this.

1. you can import the contents of myModule directly into the main namespace ( e.g. from myModule import * ). This will allow buttonPressed to be accessed without the namespace. This is not generally recommended as its clutters up your main namespace which could ultimately lead to name clashes.

2. you can change your script and prefix the function with the module it will be imported from:

   button( command="myModule.buttonPressed()" )
   

The problem with both of these solutions is that you must ensure that the module is always imported the same way, and, if you plan to share your module with someone, it’s pretty impossible to do this.

A more robust solution is to include an import command in the string to execute:

button( command="import myModule; myModule.buttonPressed()" )

That gives us a fairly reliable solution, but it still has one major drawback: any parameters that we wish to pass to our function must also be converted to strings. This becomes impractical when the parameters are complex objects, such as dictionaries, lists, or other custom objects.

So, while string callbacks may seem simple at first, they have limitations, and are generally not recommended.

Function Object¶

When using this technique, you pass an actual function object instead of a string.

from pymel.core import *

def buttonPressed():
    print "pressed!"

win = window(title="My Window")
layout = columnLayout()
btn = button(command=buttonPressed)

showWindow()

The difference from the previous example is subtle: command="buttonPressed()" is now command=buttonPressed. The most important thing to realize here is that buttonPressed is not a string, it is a python function object. As such, if we had included () ( e.g. command=buttonPressed() ) we would have executed the buttonPressed function immediately, but we don’t want that to happen yet. By leaving the parentheses off, we hand the function over to the UI element to execute later. For most commands that support callbacks, Maya recognizes when you are passing a string and when you are passing a function, and it treats each differently when the callback is triggered.

This method is very robust, but there are a few caveats to be aware of. To see what I mean, try executing the code above and pressing the button...

...when we press it, we get this error:

# TypeError: buttonPressed() takes no arguments (1 given) #

Why?! The button UI widget, like many others, automatically passes arguments to your function, whether you want them or not. Sometimes these arguments contain the state of the UI element, such as whether a checkbox is on or off, but in our case they are pretty useless.

radioButton -changeCommand "myRadButtCB #1";

So, to make our callback work, we need to modify the function to accept the argument that the button command callback is passing us:

def buttonPressed(arg):
    print "pressed!"

The tricky part is that different UI elements pass differing numbers of arguments to their callbacks, and some pass none at all. This is why it is best for your command to use the *args syntax, like so:

def buttonPressed(*args):
    print "pressed! here are my arguments %s" % ( args, )

The asterisk in front of args allows the function to accept any quantity of passed arguments. All of the positional arguments to the function are stored in the variable args (without the *) as a read-only list, known as a tuple. Making it a habit to use this syntax for your callbacks can save you a lot of headache.

Putting it all together:

from pymel.core import *

def buttonPressed(*args):
    print "pressed!"

win = window(title="My Window")
layout = columnLayout()
btn = button( command=buttonPressed )

showWindow()

Lambda Functions¶

The next technique builds on the last by simplifying the following situations:

• You want to pass arguments to your callback function other than those automatically sent by the UI element
• You’re using a function that someone else wrote and can’t add the *args to it

For example, I want to pass our buttonPressed function a name argument. Here’s how we do this using a lambda function:

from pymel.core import *

def buttonPressed(name):
    print "pressed %s!" % name

win = window(title="My Window")
layout = columnLayout()
btn = button( command = lambda *args: buttonPressed('chad') )

showWindow()

So, what exactly is a lambda? It’s a shorthand way of creating a simple function on one line. It’s usually used when you need a function but you don’t need to refer to it later by name, which makes it well suited for callbacks. Combining lambda functions with the lessons we learned above adds more versatility to command callbacks. You can choose exactly which args you want to pass along.

Let’s clarify what a lambda is. In the above example, this portion of the code...

lambda *args: buttonPressed('chad')

...could have been written as:

def tempFunc(*args):
    return buttonPressed('chad')

We would have then passed tempFunc as the callback:

btn = button( command = tempFunc )

Instead, we use the lambda to create the function on one line and pass it directly to the command flag.

btn = button( command = lambda *args: buttonPressed('chad') )

The lambda function serves as a mediator between the UI element and our real callback, buttonPressed, giving us control over what arguments will be passed to buttonPressed. In our example, we ignore all the arguments passed by the button and instead opt to pass the string 'chad', however, if the circumstances require it, you could use the arguments in args as well:

btn = button( command = lambda *args: buttonPressed('chad', args[0]) )

In the example above we’re using the first of the arguments passed by the button (remember, args is a tuple, which is like a list) and passing it on to our callback in addition to the name string. Keep in mind that for this to work our buttonPressed callback would need to be modified to accept two arguments.

Whew! That was a lot to learn, but unfortunately, this method has a drawback, too. It does not work properly when used in a ‘for’ loop.

In the following example, we’re going to make several buttons. Our intention is that each one will print a different name, but as you will soon see, we won’t succeed.

from pymel.core import *

def buttonPressed(name):
    print "pressed %s!" % name

win = window(title="My Window")
layout = columnLayout()
names = ['chad', 'robert', 'james']
for name in names:
    button( label=name, command = lambda *args: buttonPressed(name) )

showWindow()

When pressed, all the buttons will print ‘james’. Why is this? Think of a lambda as a “live” object. It lives there waiting to execute the code it has been given, but the variables in that code are live too, so the value of the variable named character changes with each iteration through the loop, thereby changing the code that lambda is waiting to execute. What is its value at the end of the loop? It’s ‘james’. So all the lambda’s execute the equivalent of:

buttonPressed('james')

To solve this we need to “pin” down the value of our variable to keep it from changing. To do this, pymel provides a Callback object...

Callback Objects¶

In my experience this method handles all cases reliably and predictably, and solves the ‘lambda’ issue described above. A Callback object is an object that behaves like a function, meaning it can be ‘called’ like a regular function. The Callback object ‘wraps’ another function, and also stores the parameters to pass to that function. And, lucky for you, the Callback class is included with pymel.

Here’s an example:

from pymel.core import *

def buttonPressed(name):
    print "pressed %s!" % name

win = window(title="My Window")
layout = columnLayout()
names = ['chad', 'robert', 'james']
for name in names:
    button( label=name, command = Callback( buttonPressed, name ) )

showWindow()

Our example now works as intended. The Callback class provides the magic that makes it work.

Pay close attention to how the Callback is created: the first argument, buttonPressed, is the function to wrap, and the rest are arguments to that function. The Callback stores the function and its arguments separately and then combines them when it is called by the UI element.

So, on assignment, something that looks like this...

Callback( buttonPressed, name )

...on execution becomes:

buttonPressed(name)

In this case, the variable name is the only additional argument, but the Callback class can accept any number of arguments or even keyword arguments, which it will dutifully pass along to your function when the callback is triggered.

The Callback class ignores any arguments passed in from the UI element, so you don’t have to design your function to take these into account. However, if you do want these, use the alternate callback object CallbackWithArgs which will pass the UI arguments after yours.

Parsed Caches and Maintained Constants¶

In order to fuse the many disparate parts of maya’s python package into a cohesive whole PyMEL requires a great deal of data describing how each MEL command and API class works: the arguments they require, the results they return, and their relationships to each other. Some of this data is parsed and cached, while other bits are manually maintained.

Below is a description of how each major cache is created.

Run Time Function and Class Factories¶

When PyMEL is imported it uses the cached data to generate the wrapped functions and classes you’ve come to know and love. Here’s how in a nutshell.

Getting Started with Git¶

The PyMEL project hosts its code on github.

1. Sign up for a Github account
2. Check out the Github Guides for instructions on how to setup git for your OS
3. Download a GUI front-end: SmartGit and TortoiseGit are by far my favorites
4. Make a fork of the main PyMEL repository, and start hacking

To get maya to use the version of pymel you have just checked out, either manually add it to your PYTHONPATH environment variable, or cd into the directory, then run:

PATH/TO/MAYA/INSTALL/bin/mayapy setup.py develop

When you “push” your changes up to Github, we’ll be able to track them, give you feedback, and cherry-pick what we like. You, in turn, will be able to easily pull new changes from our repo into yours.

Running the Tests¶

PyMEL has a suite of unit tests. You should write a test for every major addition or change that you make. To run the tests, you need ‘nose’, which is a discovery-based test runner, that builds on python’s unittest module and makes writing running a lot of tests a lot easier. Here’s the easiest way to get nose.

On linux/osx:

sudo mayapy setup.py easy_install nose

On windows:

mayapy.exe setup.py easy_install nose

This assumes that you’ve properly setup your environment, which you should definitely know how to do before contributing to PyMEL.

Module Namespaces¶

The primary feature that conceptually distinguishes a module from a MEL script is that a module by default serves as its own namespace. In other words, once the module is imported, any functions contained inside it must be referenced with the module’s name as a prefix (without the .py extension):

import myModule
myModule.myfunc()

The concept of namespaces should be familiar to anyone who has used referencing in Maya. In Maya, namespaces provide organization and help avoid conflicts between the contents of each referenced file. And like Maya, python provides the ability to modify the default namespace when importing.

Here’s how you can change the namespace:

import myModule as mod
mod.myfunc()

or you can get rid of the namespace all together:

from myModule import *
myfunc()