PlugArray

PlugArray is a collection of Maya plugs. Its filters return new collections; the plugs continue to represent the same live attributes.

om.MPlugArray→PlugArray

9properties13methods

Import

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

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

Inheritance and scope

Item	Value
Class	PlugArray
Module	weSkel.src.core.node.extensions.plugs_lib
Direct parent	om.MPlugArray
Kind	Maya API 2.0 subclass
Spec properties	None.

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

Native inherited members: om.MPlugArray — Autodesk.

Constructor

PlugArray(array: Optional[Union[Sequence[Plug], Sequence[om.MPlug], om.MPlugArray, om.MPlug]]=None) → PlugArray

Parameter	Type	Default
array	Optional[Union[Sequence[Plug], Sequence[om.MPlug], om.MPlugArray, om.MPlug]]	None

Without an argument, create an empty collection. Accepts one om.MPlug, an om.MPlugArray or a plug sequence. Use PlugArray.from_iter() for a generator. Other types raise TypeError. The collection refers to existing attributes without duplicating them.

Properties

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

Property	Return type	Access	Purpose
writable	PlugArray	R	Filter unlocked plugs without checking their connections.
keyable	PlugArray	R	Filter keyable plugs.
channel_box	PlugArray	R	Filter plugs with the Channel Box flag enabled.
locked	PlugArray	R	Filter locked plugs.
unlocked	PlugArray	R	Filter unlocked plugs.
arrays	PlugArray	R	Filter multi roots.
elements	PlugArray	R	Collect materialized elements of the included multi roots.
compounds	PlugArray	R	Filter compound plugs.
dynamic	PlugArray	R	Filter dynamic attributes.

writable

plugs.writableRead only

Return type	Contract
PlugArray	Filter unlocked plugs without checking their connections.

This filter checks only the local lock. An unlocked plug may remain unwritable because it is connected or constrained by Maya.

keyable

plugs.keyableRead only

Return type	Contract
PlugArray	Filter keyable plugs.

channel_box

plugs.channel_boxRead only

Return type	Contract
PlugArray	Filter plugs with the Channel Box flag enabled.

locked

plugs.lockedRead only

Return type	Contract
PlugArray	Filter locked plugs.

unlocked

plugs.unlockedRead only

Return type	Contract
PlugArray	Filter unlocked plugs.

This filter checks only the local lock. An unlocked plug may remain unwritable because it is connected or constrained by Maya.

arrays

plugs.arraysRead only

Return type	Contract
PlugArray	Filter multi roots.

elements

plugs.elementsRead only

Return type	Contract
PlugArray	Collect materialized elements of the included multi roots.

compounds

plugs.compoundsRead only

Return type	Contract
PlugArray	Filter compound plugs.

dynamic

plugs.dynamicRead only

Return type	Contract
PlugArray	Filter dynamic attributes.

Methods

Own methods.

Method	Return type	Purpose
to_mplug_array	om.MPlugArray	Create a native om.MPlugArray containing the same plugs.
from_iter	PlugArray	Build a collection from an iterable; class method.
filter	PlugArray	Keep plugs for which the predicate returns true.
connected	PlugArray	Filter connected plugs by source or destination role.
of_type	PlugArray	Filter by API attribute type identifiers.
match	PlugArray	Filter names with an fnmatch pattern.
disconnect_all_inputs	None	Disconnect each plug’s inputs in sequence.
disconnect_all_outputs	None	Disconnect each plug’s outputs in sequence.
disconnect_all	None	Disconnect all relationships of each plug in sequence.
connect_to	None	Connect the source collection to destinations.
connect_from	None	Connect sources to this destination collection.
disconnect_to	None	Disconnect relationships to targets; provide explicit targets.
disconnect_from	None	Disconnect relationships from sources, or the current inputs.

to_mplug_array

plugs.to_mplug_array()Method

Returns	Contract
om.MPlugArray	Create a native om.MPlugArray containing the same plugs.

from_iter

PlugArray.from_iter(iterable: Iterator[Plug])Method

Parameter	Type	Default
iterable	Iterator[Plug]	required

Returns	Contract
PlugArray	Build a collection from an iterable; class method.

filter

plugs.filter(fn: Callable[[Plug], bool])Method

Parameter	Type	Default
fn	Callable[[Plug], bool]	required

Returns	Contract
PlugArray	Keep plugs for which the predicate returns true.

connected

plugs.connected(what: str='any')Method

Parameter	Type	Default
what	str	'any'

Returns	Contract
PlugArray	Filter connected plugs by source or destination role.

what accepts only "any", "source" or "destination"; another value raises ValueError.

of_type

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

Parameter	Type	Default
attr_types	Set[int]	required

Returns	Contract
PlugArray	Filter by API attribute type identifiers.

match

plugs.match(pattern: str, where: str='full')Method

Parameter	Type	Default
pattern	str	required
where	str	'full'

Returns	Contract
PlugArray	Filter names with an fnmatch pattern.

where is "full" (native name), "long" or "short". All include the node name. Patterns use fnmatch, not regular expressions. Unknown mode: ValueError.

disconnect_all_inputs

plugs.disconnect_all_inputs()Method

Returns	Contract
None	Disconnect each plug’s inputs in sequence.

disconnect_all_outputs

plugs.disconnect_all_outputs()Method

Returns	Contract
None	Disconnect each plug’s outputs in sequence.

disconnect_all

plugs.disconnect_all()Method

Returns	Contract
None	Disconnect all relationships of each plug in sequence.

connect_to

plugs.connect_to(targets: Union['PlugArray', Plug], *, force: bool=False, clear_dest: bool=False)Method

Parameter	Type	Default
targets	Union[PlugArray, Plug]	required
force	bool	False
clear_dest	bool	False

Returns	Contract
None	Connect the source collection to destinations.

Two PlugArray objects are paired by position and must have equal lengths (ValueError otherwise). A single source can fan out through destinations.connect_from(source). Several sources into one scalar plug do not form a valid blend. Occupied targets are preserved without explicit replacement. Null plugs are skipped; check expected connections after calling. clear_dest=True or force=True replace existing destination inputs.

connect_from

plugs.connect_from(sources: Union['PlugArray', Plug], *, force: bool=False, clear_src: bool=False)Method

Parameter	Type	Default
sources	Union[PlugArray, Plug]	required
force	bool	False
clear_src	bool	False

Returns	Contract
None	Connect sources to this destination collection.

Two PlugArray objects are paired by position and must have equal lengths (ValueError otherwise). A single source can fan out through destinations.connect_from(source). Several sources into one scalar plug do not form a valid blend. Occupied targets are preserved without explicit replacement. Null plugs are skipped; check expected connections after calling. Despite its name, clear_src=True clears the input of self’s destinations, not the source’s outputs. Here it has the same replacement effect as force=True.

disconnect_to

plugs.disconnect_to(targets: Optional[Union['PlugArray', Plug]]=None)Method

Parameter	Type	Default
targets	Optional[Union[PlugArray, Plug]]	None

Returns	Contract
None	Disconnect relationships to targets; provide explicit targets.

Reproduced limitation: without targets, the current path uses an incompatible connectedTo signature and raises TypeError. Supply an explicit Plug or PlugArray, or use disconnect_all_outputs(). Two collections must have matching lengths.

disconnect_from

plugs.disconnect_from(sources: Optional[Union['PlugArray', Plug]]=None)Method

Parameter	Type	Default
sources	Optional[Union[PlugArray, Plug]]	None

Returns	Contract
None	Disconnect relationships from sources, or the current inputs.

sources=None removes current native inputs. A single plug applies to every destination; two collections pair by position and require equal lengths. Lock flags are restored.

Python access

Expression	Returns	Behavior
len(plugs)	int	Entry count.
plugs[index]	Plug	Non-negative collection index; negative/out of range: IndexError. Slices are not supported by this override.
for plug in plugs	Iterator[Plug]	Iterate through the collection in order.

Behavior to remember

Filters do not change the original collection. Membership reflects the time of filtering, but plug values remain live. PlugArray is neither a multi attribute nor a list of values.

Collection connections do not blend values. The disconnect_all_* methods process plugs sequentially: do not assume global rollback if a later call fails.

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 PlugArray

suffix = uuid4().hex[:8]
driver = Transform("sdk_driver_" + suffix)
follower = Transform("sdk_follower_" + suffix)
try:
    driver.create()
    follower.create()
    source = driver.plugs["scaleX"]
    source.value = 3.0
    targets = PlugArray([follower.plugs[name] for name in
                         ("scaleX", "scaleY", "scaleZ")])
    targets.connect_from(source)
    assert len(targets.connected("destination")) == 3
    assert [plug.value for plug in targets] == [3.0, 3.0, 3.0]
    assert len(targets.match("*scaleY")) == 1
    targets.disconnect_from(source)
    assert all(plug.src is None for plug in targets)
    print("PlugArray: PASS")
finally:
    follower.delete(snapshot=False)
    driver.delete(snapshot=False)

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

See also: Plug · Plugs.