Wrappers & specs

Wrappers provide Python names and operations for Maya nodes. Specs describe the properties those wrappers expose.

Current reference

This page describes behavior available in the current code. The guide for creating a user extension will be added after that workflow is validated with the compiled engine.

Useful concepts

Concept	Role	Example
Wrapper	A Python object representing a Maya node.	Transform, Joint, MultMatrix
Property	A named wrapper access to a value or capability.	transform.scale
Plug	A Maya attribute whose value or connections can be accessed.	transform.plugs["scale"]
Spec	A property declaration: public name, Maya name, type, default value and flags.	matrix_sum maps to matrixSum.
Spec layer	A set of specs combined with those of parent classes.	General node properties followed by MultMatrix properties.

Declaring a spec does not, by itself, create a new dynamic attribute in Maya. Use the concrete wrapper for the intended node type.

Read specs without editing the scene

In Maya’s Python Script Editor, with weSkel available:

from weSkel.src.core.node.dg.mult_matrix.lib import MultMatrix
from weSkel.src.core.props.specs.specs_layers import merged_specs_for_cls

specs = merged_specs_for_cls(MultMatrix)
public_name, plug_name, cache_name, kind, default_value, flags = specs["matrix_sum"]

assert public_name == "matrix_sum"
assert plug_name == "matrixSum"
assert kind == "typed:matrix"
assert "output" in flags and "connectable" in flags

print(public_name, "->", plug_name)
print("Kind:", kind)
print("Flags:", flags)

Expected result: matrix_sum -> matrixSum, the typed:matrix kind and the property flags. This example does not create any nodes.

Field	Meaning
public_name	The Python-facing name, here matrix_sum.
plug_name	The Maya attribute name or path, here matrixSum.
cache_name	An internal declaration field; do not use it as a scripting API.
kind	The value category, here a matrix.
default_value	The declared default; this is not a scene read.
flags	Indicators such as output, connectable or stored, depending on the property.

The result merges the wrapper’s layers and its parents’ layers. Use it to inspect declarations without modifying it in place.

A few useful access patterns

Need	Current access	Keep in mind
Create a transform	Transform(name), then node.create()	create() returns None.
Read or write a plug value	node.plugs["scaleX"].value	Connected or locked attributes impose their constraints.
Read a plug’s source	plug.src	Check the connection that was actually obtained.
Connect two plugs	source.connect_to(destination)	Does not replace an existing source by default.
Read array indices	plug.logical_indices	Maya indices may be non-contiguous.
Inspect a live property	node.svd("scale")	The view follows the scene; it is not a saved state.
Capture a targeted state	node.snapshot_svd(("scale",))	Produces a targeted record, distinct from the dictionary below.
Capture the state described by specs	node.snapshot()	Produces the dictionary accepted by node.finalize(snapshot).

Snapshots are not a complete scene backup. They may contain Maya objects and are not automatically JSON-serializable. Low-level replay does not replace a complete module rebuild operation.

Values, units and object lifetime

Situation	Keep in mind
Scale	Unitless values; used in First script.
Angles, distances and time read through Plug.value	Values may be Maya API 2.0 MAngle, MDistance or MTime objects.
Properties derived from specs	The kind described by the spec guides access; do not assume all properties and plugs return the same representation.
Deleted node or attribute	Do not reuse an old Plug object for a new object with the same name.
Updating weSkel	Restart Maya to load the new installation.

Return to API & SDK for distribution limits and capabilities still in preparation.