Plugs

Node attribute access and dynamic plug creation.

ClassAPI 2.0SDK

Plugs manages attributes of a DGNode wrapper or descendant. The usual entry point is node.plugs.

objectPlugs

Import

from weSkel.src.core.node.extensions.plugs_lib import Plugs

Run in Maya with weSkel available. om.* types refer to maya.api.OpenMaya.

Inheritance and scope

Item	Value
Class	`Plugs`
Module	`weSkel.src.core.node.extensions.plugs_lib`
Direct parent	`object`
Kind	Node attribute manager
Spec properties	None.

This reference documents members defined by this class. Standard Python mechanisms and native inherited members are outside its member counts.

Constructor

Plugs(node: 'DGNode') → Plugs

Parameter	Type	Default
`node`	`DGNode`	required

Supply a DGNode wrapper or descendant, not its name or MObject directly. node.plugs already provides this manager. Construction creates no node. The public node field retains the wrapper; avoid reassigning it after caching.

Fields

Own members. R = read only; R/W = read and write.

Field	Return type	Access	Purpose
`node`	`DGNode`	R/W	Wrapper whose plugs the manager exposes.

node

plugs.nodeRead / write

Return type	Contract
`DGNode`	Wrapper whose plugs the manager exposes.

Properties

Own members. R = read only; R/W = read and write.

Property	Return type	Access	Purpose
`all`	`Optional[PlugArray]`	R	Cached plug inventory, including compounds and existing elements.
`locked`	`Optional[List[Tuple[str, bool]]]`	R	List of names and lock flags for all inventoried plugs.
`keyables`	`Optional[List[Tuple[str, bool]]]`	R	List of names and keyable flags for all inventoried plugs.
`compounds`	`Optional[PlugArray]`	R	Compound plugs from the inventory.
`arrays`	`Optional[PlugArray]`	R	Multi roots from the inventory.
`dynamics`	`Optional[PlugArray]`	R	Dynamic attributes from the inventory.
`transforms`	`Optional[PlugArray]`	R	Translate, rotate, scale and shear channels present in the inventory.

all

plugs.allRead only

Return type	Contract
`Optional[PlugArray]`	Cached plug inventory, including compounds and existing elements.

The inventory caches structure, not values. After additions or removals outside this manager, call refresh(). Children and elements are traversed; do not assume the list contains only root attributes or that every attribute object is unique.

locked

plugs.lockedRead only

Return type	Contract
`Optional[List[Tuple[str, bool]]]`	List of names and lock flags for all inventoried plugs.

The result includes both True and False states. For a filtered plug collection use plugs.all.locked or plugs.all.keyable after checking all is not None. Returned names include the node.

keyables

plugs.keyablesRead only

Return type	Contract
`Optional[List[Tuple[str, bool]]]`	List of names and keyable flags for all inventoried plugs.

compounds

plugs.compoundsRead only

Return type	Contract
`Optional[PlugArray]`	Compound plugs from the inventory.

arrays

plugs.arraysRead only

Return type	Contract
`Optional[PlugArray]`	Multi roots from the inventory.

dynamics

plugs.dynamicsRead only

Return type	Contract
`Optional[PlugArray]`	Dynamic attributes from the inventory.

transforms

plugs.transformsRead only

Return type	Contract
`Optional[PlugArray]`	Translate, rotate, scale and shear channels present in the inventory.

Methods

Own methods.

Method	Return type	Purpose
`get`	`Optional[Plug]`	Resolve an attribute name or index; fall back to the supplied default or a null plug.
`find`	`PlugArray`	Find by pattern in names that include the node.
`keys`	`list[str]`	Return inventoried plug names, including the node prefix.
`items`	`list[tuple[str, Plug]]`	Return name and plug pairs from the inventory.
`refresh`	`None`	Rebuild the plug inventory immediately.
`rename_plug`	`Plug`	Rename a dynamic attribute and return the renamed plug.
`has_plug`	`bool`	Check a name on the node, or whether a supplied MPlug is non-null.
`attribute_names`	`list[str]`	Return plug names including the node name.
`attribute_objects`	`list[om.MObject]`	Return attribute objects from the inventory.
`get_attr_obj_at_index`	`om.MObject`	Resolve a physical index in the node’s native attribute list.
`get_attr_fn_at_index`	`om.MFnAttribute`	Return the function set of the attribute at this physical index.
`of_type`	`Optional[PlugArray]`	Filter plugs by type; `None` when none match.
`add_enum_plug`	`Plug`	Create a dynamic enum attribute, numbered from zero.
`add_generic_plug`	`Plug`	Create a dynamic generic attribute.
`add_matrix_plug`	`Plug`	Create a dynamic matrix attribute.
`add_message_plug`	`Plug`	Create a scalar or multi message attribute.
`add_numeric_plug`	`Plug`	Create a numeric attribute with optional default and bounds.
`add_bool_plug`	`Plug`	Create a dynamic boolean attribute.
`add_typed_plug`	`Plug`	Create a typed attribute; supply a compatible type and default data.
`add_string_plug`	`Plug`	Create a dynamic string attribute.
`add_unit_plug`	`Plug`	Currently incompatible unit-creation call; see the limitation.
`ensure_matrix_plug`	`Plug`	Find a compatible dynamic matrix attribute or create it.
`ensure_string_plug`	`Plug`	Find a compatible dynamic string attribute or create it.
`ensure_message_plug`	`Plug`	Find a compatible dynamic message attribute or create it.
`set_locked`	`None`	Set lock flags for the supplied names, then refresh the inventory.
`set_keyable`	`None`	Set keyable flags for the supplied names, then refresh.
`set_channel_box`	`None`	Set Channel Box flags for the supplied names, then refresh.
`lock_all`	`None`	Lock the inventoried plugs.
`unlock_all`	`None`	Unlock the inventoried plugs.
`keyable_all`	`None`	Enable the keyable flag of inventoried plugs.
`unkeyable_all`	`None`	Disable the keyable flag of inventoried plugs.
`channel_box_all`	`None`	Enable the Channel Box flag of inventoried plugs.
`no_channel_box_all`	`None`	Disable the Channel Box flag of inventoried plugs.
`remove`	`None`	Remove an attribute from the node and refresh the inventory.
`clear_cache`	`None`	Invalidate the inventory; the next access to `all` rebuilds it.

get

plugs.get(keyname: Union[int, str], default: Optional['Plug']=None)Method

Parameter	Type	Default
`keyname`	`Union[int, str]`	required
`default`	`Optional[Plug]`	`None`

Returns	Contract
`Optional[Plug]`	Resolve an attribute name or index; fall back to the supplied default or a null plug.

A missing name or invalid index returns a supplied non-null default, otherwise a null Plug. In contrast, plugs["missing"] normally returns None. Integer indices are native attribute positions on the node, not multi logical indices.

find

plugs.find(pattern: str, where: str='attr')Method

Parameter	Type	Default
`pattern`	`str`	required
`where`	`str`	`'attr'`

Returns	Contract
`PlugArray`	Find by pattern in names that include the node.

Even with where="attr", matching uses a name including the node. Use a pattern such as "*scaleX". Valid modes are "attr", "long" and "short"; an invalid mode raises ValueError when the inventory is non-empty.

keys

plugs.keys(mode: str='attr')Method

Parameter	Type	Default
`mode`	`str`	`'attr'`

Returns	Contract
`list[str]`	Return inventoried plug names, including the node prefix.

These results include the node prefix despite the names attr or attribute_names. keys("attr") uses long_name; items("attr") uses native name(). For an unprefixed name read plug.long_attribute_name.

items

plugs.items(mode: str='attr')Method

Parameter	Type	Default
`mode`	`str`	`'attr'`

Returns	Contract
`list[tuple[str, Plug]]`	Return name and plug pairs from the inventory.

refresh

plugs.refresh()Method

Returns	Contract
`None`	Rebuild the plug inventory immediately.

rename_plug

plugs.rename_plug(old_name: str, new_name: str, *, force_refresh: bool=True)Method

Parameter	Type	Default
`old_name`	`str`	required
`new_name`	`str`	required
`force_refresh`	`bool`	`True`

Returns	Contract
`Plug`	Rename a dynamic attribute and return the renamed plug.

For dynamic attributes only. Missing name, occupied target name or native attribute: ValueError. Both long and short names become new_name. force_refresh=False skips the immediate inventory rebuild.

has_plug

plugs.has_plug(plug: Union[str, om.MPlug])Method

Parameter	Type	Default
`plug`	`Union[str, om.MPlug]`	required

Returns	Contract
`bool`	Check a name on the node, or whether a supplied MPlug is non-null.

With a str, resolve the attribute on the managed node. With an om.MPlug, only check non-nullity: this does not prove that it belongs to this node.

attribute_names

plugs.attribute_names(*, short: bool=True)Method

Parameter	Type	Default
`short`	`bool`	`True`

Returns	Contract
`list[str]`	Return plug names including the node name.

attribute_objects

plugs.attribute_objects()Method

Returns	Contract
`list[om.MObject]`	Return attribute objects from the inventory.

get_attr_obj_at_index

plugs.get_attr_obj_at_index(index: int)Method

Parameter	Type	Default
`index`	`int`	required

Returns	Contract
`om.MObject`	Resolve a physical index in the node’s native attribute list.

get_attr_fn_at_index

plugs.get_attr_fn_at_index(index: int)Method

Parameter	Type	Default
`index`	`int`	required

Returns	Contract
`om.MFnAttribute`	Return the function set of the attribute at this physical index.

of_type

plugs.of_type(attr_types: Set[int])Method

Parameter	Type	Default
`attr_types`	`Set[int]`	required

Returns	Contract
`Optional[PlugArray]`	Filter plugs by type; `None` when none match.

add_enum_plug

plugs.add_enum_plug(long_name: str, short_name: Optional[str]=None, enum_names: Optional[List[str]]=None, default_value: Optional[int]=None)Method

Parameter	Type	Default
`long_name`	`str`	required
`short_name`	`Optional[str]`	`None`
`enum_names`	`Optional[List[str]]`	`None`
`default_value`	`Optional[int]`	`None`

Returns	Contract
`Plug`	Create a dynamic enum attribute, numbered from zero.

short_name=None reuses the long name. default_value=None becomes 0; enum_names fields are numbered 0, 1, 2…. The inventory is refreshed after creation.

add_generic_plug

plugs.add_generic_plug(long_name: str, short_name: Optional[str]=None)Method

Parameter	Type	Default
`long_name`	`str`	required
`short_name`	`Optional[str]`	`None`

Returns	Contract
`Plug`	Create a dynamic generic attribute.

add_matrix_plug

plugs.add_matrix_plug(long_name: str, short_name: Optional[str]=None, plug_type: Optional[int]=None, *, nice_name: Optional[str]=None, categories: Optional[Iterable[str]]=None)Method

Parameter	Type	Default
`long_name`	`str`	required
`short_name`	`Optional[str]`	`None`
`plug_type`	`Optional[int]`	`None`
`nice_name`	`Optional[str]`	`None`
`categories`	`Optional[Iterable[str]]`	`None`

Returns	Contract
`Plug`	Create a dynamic matrix attribute.

Default type: om.MFnMatrixAttribute.kDouble. The short name reuses the long name when omitted. nice_name and categories add attribute metadata; this signature accepts no custom default matrix.

add_message_plug

plugs.add_message_plug(long_name: str, short_name: Optional[str]=None, *, array: bool=False, index_matters: Optional[bool]=None)Method

Parameter	Type	Default
`long_name`	`str`	required
`short_name`	`Optional[str]`	`None`
`array`	`bool`	`False`
`index_matters`	`Optional[bool]`	`None`

Returns	Contract
`Plug`	Create a scalar or multi message attribute.

index_matters is allowed only with array=True (ValueError otherwise). False creates an unreadable destination multi. An ensure checks multi shape and the requested flag without rewriting an incompatible attribute.

add_numeric_plug

plugs.add_numeric_plug(long_name: str, short_name: Optional[str]=None, numeric_type: Optional[int]=None, default_value: Optional[float]=None, min_value: Optional[float]=None, max_value: Optional[float]=None)Method

Parameter	Type	Default
`long_name`	`str`	required
`short_name`	`Optional[str]`	`None`
`numeric_type`	`Optional[int]`	`None`
`default_value`	`Optional[float]`	`None`
`min_value`	`Optional[float]`	`None`
`max_value`	`Optional[float]`	`None`

Returns	Contract
`Plug`	Create a numeric attribute with optional default and bounds.

short_name=None reuses the long name. The default numeric type is om.MFnNumericData.kDouble, or kBoolean for add_bool_plug. The default value is zero; bounds are applied only when supplied.

add_bool_plug

plugs.add_bool_plug(long_name: str, short_name: Optional[str]=None, default_value: Optional[bool]=None)Method

Parameter	Type	Default
`long_name`	`str`	required
`short_name`	`Optional[str]`	`None`
`default_value`	`Optional[bool]`	`None`

Returns	Contract
`Plug`	Create a dynamic boolean attribute.

short_name=None reuses the long name. The default numeric type is om.MFnNumericData.kDouble, or kBoolean for add_bool_plug. The default value is zero; bounds are applied only when supplied.

add_typed_plug

plugs.add_typed_plug(long_name: str, short_name: Optional[str]=None, typed_type: Union[int, om.MTypeId, om.MFnData, None]=None, default_value: Optional[Any]=None)Method

Parameter	Type	Default
`long_name`	`str`	required
`short_name`	`Optional[str]`	`None`
`typed_type`	`Union[int, om.MTypeId, om.MFnData, None]`	`None`
`default_value`	`Optional[Any]`	`None`

Returns	Contract
`Plug`	Create a typed attribute; supply a compatible type and default data.

The typed_type=None default selects om.MFnData.kNumeric, but default data is a string: calling without an explicit type fails in the tested Maya versions. For a typed array supply its om.MFnData type and a compatible data om.MObject; a Python list is not automatically converted. For strings prefer add_string_plug().

add_string_plug

plugs.add_string_plug(long_name: str, short_name: Optional[str]=None, default_value: Optional[str]=None)Method

Parameter	Type	Default
`long_name`	`str`	required
`short_name`	`Optional[str]`	`None`
`default_value`	`Optional[str]`	`None`

Returns	Contract
`Plug`	Create a dynamic string attribute.

Without an explicit value, create an empty string. The short name reuses the long name when omitted. Use ensure_string_plug() if the attribute may already exist.

add_unit_plug

plugs.add_unit_plug(long_name: str, short_name: Optional[str]=None, unit_type: Optional[int]=None, default_value: Optional[float]=None)Method

Parameter	Type	Default
`long_name`	`str`	required
`short_name`	`Optional[str]`	`None`
`unit_type`	`Optional[int]`	`None`
`default_value`	`Optional[float]`	`None`

Returns	Contract
`Plug`	Currently incompatible unit-creation call; see the limitation.

Reproduced limitation in Maya 2025.3 and 2026.3: TypeError. The current path passes four arguments to native creation. This attribute constructor is not presented as operational; existing unit plugs remain readable through Plug.

ensure_matrix_plug

plugs.ensure_matrix_plug(long_name: str, short_name: Optional[str]=None, plug_type: Optional[int]=None, *, nice_name: Optional[str]=None, categories: Optional[Iterable[str]]=None)Method

Parameter	Type	Default
`long_name`	`str`	required
`short_name`	`Optional[str]`	`None`
`plug_type`	`Optional[int]`	`None`
`nice_name`	`Optional[str]`	`None`
`categories`	`Optional[Iterable[str]]`	`None`

Returns	Contract
`Plug`	Find a compatible dynamic matrix attribute or create it.

An existing attribute must be dynamic and compatible; otherwise RuntimeError, without automatic replacement. Short-name parameters are used only for creation. An ensure does not overwrite an existing value or connection.

ensure_string_plug

plugs.ensure_string_plug(long_name: str, short_name: Optional[str]=None, default_value: Optional[str]=None)Method

Parameter	Type	Default
`long_name`	`str`	required
`short_name`	`Optional[str]`	`None`
`default_value`	`Optional[str]`	`None`

Returns	Contract
`Plug`	Find a compatible dynamic string attribute or create it.

ensure_message_plug

plugs.ensure_message_plug(long_name: str, short_name: Optional[str]=None, *, array: bool=False, index_matters: Optional[bool]=None)Method

Parameter	Type	Default
`long_name`	`str`	required
`short_name`	`Optional[str]`	`None`
`array`	`bool`	`False`
`index_matters`	`Optional[bool]`	`None`

Returns	Contract
`Plug`	Find a compatible dynamic message attribute or create it.

set_locked

plugs.set_locked(names: Sequence[str], state: bool)Method

Parameter	Type	Default
`names`	`Sequence[str]`	required
`state`	`bool`	required

Returns	Contract
`None`	Set lock flags for the supplied names, then refresh the inventory.

set_keyable

plugs.set_keyable(names: Sequence[str], state: bool)Method

Parameter	Type	Default
`names`	`Sequence[str]`	required
`state`	`bool`	required

Returns	Contract
`None`	Set keyable flags for the supplied names, then refresh.

set_channel_box

plugs.set_channel_box(names: Sequence[str], state: bool)Method

Parameter	Type	Default
`names`	`Sequence[str]`	required
`state`	`bool`	required

Returns	Contract
`None`	Set Channel Box flags for the supplied names, then refresh.

lock_all

plugs.lock_all()Method

Returns	Contract
`None`	Lock the inventoried plugs.

unlock_all

plugs.unlock_all()Method

Returns	Contract
`None`	Unlock the inventoried plugs.

keyable_all

plugs.keyable_all()Method

Returns	Contract
`None`	Enable the keyable flag of inventoried plugs.

unkeyable_all

plugs.unkeyable_all()Method

Returns	Contract
`None`	Disable the keyable flag of inventoried plugs.

channel_box_all

plugs.channel_box_all()Method

Returns	Contract
`None`	Enable the Channel Box flag of inventoried plugs.

no_channel_box_all

plugs.no_channel_box_all()Method

Returns	Contract
`None`	Disable the Channel Box flag of inventoried plugs.

remove

plugs.remove(name: Union[str, om.MPlug])Method

Parameter	Type	Default
`name`	`Union[str, om.MPlug]`	required

Returns	Contract
`None`	Remove an attribute from the node and refresh the inventory.

Missing names and null plugs are ignored. Actual removal uses Maya and may reject native or non-removable attributes. Supply a plug belonging to the managed node; no ownership validation is added for an external MPlug.

clear_cache

plugs.clear_cache()Method

Returns	Contract
`None`	Invalidate the inventory; the next access to `all` rebuilds it.

Python access

Expression	Returns	Behavior
`plugs["attribute"]`	`Plug \| None`	Long name, short alias or indexed path; `None` when absent.
`len(plugs)`	`int`	Size of the `all` inventory, or zero.
`for plug in plugs`	`Iterator[Plug]`	Iterate through the current inventory.

Behavior to remember

all caches the inventory. After an external structural change, call refresh(); call clear_cache() to defer rebuilding. Values read through each plug remain live.

The add_* methods create attributes immediately. The ensure_* methods reuse only a compatible dynamic attribute, without implicit migration. None of these calls alone guarantees a user Undo command.

Usage example

from uuid import uuid4
from weSkel.src.core.node.dag.transform.lib import Transform
from weSkel.src.core.node.extensions.plugs_lib import Plugs

node = Transform("sdk_attributes_" + uuid4().hex[:8])
try:
    node.create()
    plugs = node.plugs
    assert isinstance(plugs, Plugs)
    gain = plugs.add_numeric_plug("sdkGain", default_value=0.5,
                                  min_value=0.0, max_value=1.0)
    gain.value = 0.75
    label = plugs.ensure_string_plug("sdkLabel", default_value="rig")
    assert plugs.ensure_string_plug("sdkLabel", default_value="other") == label
    assert label.value == "rig"
    gain = plugs.rename_plug("sdkGain", "sdkWeight")
    assert gain.value == 0.75
    assert len(plugs.find("*sdkWeight")) == 1
    assert plugs["missingSdkAttribute"] is None
    assert plugs.get("missingSdkAttribute").is_null
    plugs.remove("sdkWeight")
    assert not plugs.has_plug("sdkWeight")
    print("Plugs: PASS")
finally:
    node.delete(snapshot=False)

Expected result: Plugs: PASS. Temporary nodes are removed in finally.