maya-brew

Status: Pre-Alpha – Interfaces are experimental and may change without notice. Pin exact versions if using in automation.

What you need after a long day of wrestling with Maya Python.

Overview

maya-brew aims to provide safer, more structured interaction patterns when scripting or tooling inside Autodesk Maya.

Goals:

• Reduce foot‑guns when using Python inside Maya
• Offer utilities that behave well with Maya’s quirks

Background

maya-brew draws inspiration from some of the ergonomic goals that motivated PyMEL: making Maya’s Python interface feel more “Pythonic,” safer, and more discoverable. PyMEL historically provided rich object wrappers around nodes, attributes, and other scene elements; for many workflows this improved readability and reduced boilerplate.

However, over time several practical factors led to the decision to start a lightweight alternative instead of extending PyMEL itself:

• Scope & Complexity: PyMEL’s dynamic wrapping and layered abstractions can introduce startup overhead, indirection, and occasional debugging friction.
• Historical Churn: A long evolution, multiple contributors, and some legacy design choices make selective modernization non‑trivial.
• Maintenance & Momentum: While still usable, PyMEL no longer appears to have the same pace of active development or broad community push it once did.
• Adoption Fit: Many pipelines only need a thin set of safety/ergonomic helpers—not a full object layer over maya.cmds.

Acknowledgment

PyMEL significantly influenced how many technical artists approach Maya scripting, and this project stands on that conceptual foundation. maya-brew simply narrows the focus: take the useful ergonomic ideas, shed the heavy wrapping, and keep to the canonical APIs.

Native node wrappers

User-facing exceptions are defined in maya_brew.exceptions. Catch specific failures such as NoMatchingNodes, broader categories such as NodeCastingException, or MayaBrewException for all library-defined errors.

Python node classes follow Maya's node-type inheritance, including intermediate ancestors. cast selects the exact native class for an existing node; direct constructors remain explicit.

from maya_brew.nodes.casting import cast
from maya_brew.nodes.node_types import Transform

node = cast("my_transform")
assert isinstance(node, Transform)

transform = cast("my_transform", Transform)  # Typed and checked as Transform

Command wrappers

maya_brew.command_wrapper provides typed wrappers around selected maya.cmds commands, accepting brew objects and returning native node wrappers where appropriate. Return types may differ from Maya's conventions, including typed tuples instead of lists and enums instead of numeric values. maya_brew.cmds remains the raw Maya command module.

Currently wrapped commands:

• createNode
• polyPlane

Run mayapy -m tools.generate to regenerate signatures from Maya's command help and tool-side metadata. Handwritten stubs supply command-specific typing where needed.

Generated hierarchies

Offline generation infrastructure lives in tools/node_hierarchy, outside the installed runtime package. Its versioned outputs live exclusively in src/maya_brew/nodes/_generated/maya_<version>:

The runtime selects generated classes by Maya's major version, with runtime fallback for missing releases or types.