PyMEL Documentation

The Attribute class in pymel.core.general provides a unified interface for all attribute-related operations, replacing the various MEL commands. Method names follow a simplified pattern based on standard Maya commands:

• setAttr becomes Attribute.set
• getAttr becomes Attribute.get
• connectAttr becomes Attribute.connect

Example usage on a camera node:

from pymel.core import *
import pymel.core.general as general

cam = general.PyNode('persp')
if cam.visibility.isKeyable() and not cam.visibility.isLocked():
    cam.visibility.set(True)
    cam.visibility.lock()

print cam.v.type()  # shortnames also work

The Bridge is a specialized control mechanism (managed via a GUI) that governs the interaction between MEL and the Maya API when generating PyNode classes. It allows developers to:

• Create manual overrides to correct input and output types.
• Map MEL commands to equivalent API commands.
• Specify whether a specific PyMEL method should be implemented using MEL or the API.
• Define the specific name of the resulting Python method.

Maya provides two primary ways to interact with its core via Python, which serve different purposes:

1. maya.cmds: An automatic wrapper around MEL commands. While powerful and covering thousands of commands, it is procedural and often feels 'unpythonic' or awkward because it is a direct translation of MEL functions into Python. It often returns types like None where a Pythonic API might return an empty list.

2. PyMEL: A 'restructured wrap' that uses the existing Maya Python modules as building blocks to create an intuitive, object-oriented API. PyMEL is designed to be more legible, follows Python idioms, and provides a complete object-oriented design for working with nodes and attributes.

PyMEL's primary goals are to fix bugs in maya.cmds, improve its behavior to be more Pythonic, and provide a structured object-oriented interface.

PyMEL is designed to bridge the gap between the procedural nature of MEL/maya.cmds and a true Pythonic, object-oriented experience. It aims to solve three core problems:

1. Fixing bugs found in maya.cmds.
2. Improving workflow by making maya.cmds behavior more Pythonic (e.g., returning empty lists instead of None).
3. Providing a complete object-oriented design for interacting with Maya nodes, attributes, and other structures.

PyMEL strikes a balance between the verbosity of the Maya C++ API and the unorganized, procedural nature of MEL.

In MEL, procedures might be automatically available if the script is on the MAYA_SCRIPT_PATH. In Python, you must be explicit: any .py file on your PYTHONPATH is a module and must be imported using the import statement in every script that uses it.

# MEL
source "myScript.mel";

# Python
import myModule

PyMEL provides convenient aliases for the specialized classes returned by pymel.core functions. Instead of importing the full paths, you can use these short aliases which are automatically imported into the pymel.core namespace:

• Data Types: Use pymel.core.dt to access classes in pymel.core.datatypes.
• Node Types: Use pymel.core.nt to access classes in pymel.core.nodetypes (classes corresponding to Maya node types).
• UI Types: Use pymel.core.ui to access classes in pymel.core.uitypes (classes corresponding to Maya UI types).

PyMEL provides a much cleaner interface for calling MEL procedures compared to maya.mel.eval. It allows you to call MEL procedures as if they were Python functions, passing arguments directly. Additionally, PyMEL provides specific MEL error messages with line numbers in Python tracebacks and allows interacting with MEL global variables via a dictionary-like interface.

# Calling a MEL procedure with arguments
values = ['one', 'two', 'three', 'four']
pm.mel.stringArrayRemoveDuplicates(values)

# Accessing and setting MEL global variables
print(pm.melGlobals['gMainFileMenu'])
pm.melGlobals['gGridDisplayGridLinesDefault'] = 2

To allow for name parsing and string manipulation of objects that are not yet in the scene, PyMEL provides specialized classes in the other module. These classes contain methods for string parsing and existence testing without requiring the node to exist in Maya.

Available classes in pymel.other:

• other.NameParser
• other.AttributeName
• other.DependNodeName
• other.DagNodeName

PyMEL provides an object-oriented approach to building Maya GUIs. Every UI command available in maya.cmds has a corresponding class in PyMEL derived from PyUI <pymel.core.uitypes.PyUI>.

When you use procedural UI commands (like window() or button()), PyMEL automatically returns a PyUI class instance instead of a simple string name. These instances allow you to get and set properties directly using methods on the object, rather than passing names back into commands.

from pymel.core import *

# Procedural commands return PyUI objects
win = window(title="My Window")
layout = columnLayout()
chkBox = checkBox(label="My Checkbox", value=True, parent=layout)
btn = button(label="My Button", parent=layout)

# You can interact with the objects directly
print(chkBox.getValue())
btn.setLabel("New Label")

win.show()