API Reference: connections_node

advBlendshapeTools.api.connections_node records a node’s attribute connections onto a singleton network node named abt_connections_node and replays them onto other nodes. The module is importable from inside Maya or from mayapy during pipeline scripts.

Connection data is stored in a multi compound attribute named connections, with children a_name, a_input and a_outputs. a_outputs holds a comma delimited plug list.

ConnectionsNode

class advBlendshapeTools.api.connections_node.ConnectionsNode(node: str)

Singleton network node storing attribute names with their connections.

The stored data is generic. Nothing records which node it was captured from, so it can be applied to any node whose attribute names match.

NODE_NAME = 'abt_connections_node'

ARRAY_ATTR = 'connections'

NAME_ATTR = 'a_name'

INPUT_ATTR = 'a_input'

OUTPUTS_ATTR = 'a_outputs'

__init__(node: str)

Initialize ConnectionsNode.

Parameters:

node – Name of an existing network node.

__str__() → str

Return str(self).

classmethod find() → ConnectionsNode | None

Find the connections node in the current scene.

Returns:

The node, or None when it does not exist.

Return type:

Optional[ConnectionsNode]

classmethod create() → ConnectionsNode

Create the connections node and add its attribute schema.

Returns:

The newly created node.

Return type:

ConnectionsNode

Raises:

ConnectionsNodeError – If a node of that name already exists.

classmethod get_or_create() → ConnectionsNode

Return the existing connections node, creating it when absent.

Returns:

The existing or newly created node.

Return type:

ConnectionsNode

classmethod capture(source_node: str, attribute_names: list[str] | None = None) → ConnectionsNode

Capture a node’s connections into the scene connections node.

Replaces any previously captured data. The connections node is created when it does not already exist.

Parameters:

• source_node – Name of the node to read.

• attribute_names – Attributes to record. When None, every blendShape target alias on source_node is used.

Returns:

The connections node holding the captured data.

Return type:

ConnectionsNode

property connections: list[dict]

Stored entries with ‘name’, ‘input’ and ‘outputs’ keys.

Type:

list[dict]

clear() → None

Remove every element from the connections array.

apply(destination_nodes: list[str]) → ApplyResult

Rebuild the stored connections on the given nodes.

Parameters:

destination_nodes – Names of the nodes to receive the connections.

Returns:

Counts and details of what was connected, skipped and failed.

Return type:

ApplyResult

export_json(file_path: str) → None

Write the stored connections to a JSON file.

Parameters:

file_path – Destination path.

classmethod load_json(file_path: str) → list[dict]

Read connection entries from a JSON file.

Parameters:

file_path – Path to the JSON file.

Returns:

Entries with ‘name’, ‘input’ and ‘outputs’ keys.

Return type:

list[dict]

delete() → None

Delete the connections node from the scene.

ApplyResult

class advBlendshapeTools.api.connections_node.ApplyResult(connected: list[str] = <factory>, already_connected: list[str] = <factory>, skipped: list[tuple[str, str]] = <factory>, failed: list[tuple[str, str]] = <factory>)

Outcome of applying connection data to one or more destination nodes.

connected

‘source -> destination’ strings for connections that were made.

Type:

list[str]

already_connected

Pairs that were connected before the apply ran.

Type:

list[str]

skipped

(subject, reason) pairs that were not attempted.

Type:

list[tuple[str, str]]

failed

(pair, reason) pairs where connectAttr raised.

Type:

list[tuple[str, str]]

Module-level helpers

advBlendshapeTools.api.connections_node.capture_connections(source_node: str, attribute_names: list[str] | None = None) → list[dict]

Record the input and output connections of a node’s attributes.

combinationShape plugs are skipped on both sides, whether they drive an attribute or are driven by one, since that network is rebuilt by the combination shape operations rather than restored from this data. Attributes with neither an input nor any remaining outputs are skipped as there is nothing to restore. Nothing is disconnected.

Parameters:

• source_node – Name of the node to read.

• attribute_names – Attributes to record. When None, every blendShape target alias on source_node is used.

Returns:

Entries with ‘name’, ‘input’ and ‘outputs’ keys.

Return type:

list[dict]

Raises:

ConnectionsNodeError – If source_node does not exist, or if attribute_names is None and source_node is not a blendShape.

advBlendshapeTools.api.connections_node.apply_connection_data(entries: list[dict], destination_nodes: list[str]) → ApplyResult

Rebuild stored connections on one or more destination nodes.

The destination plug for each entry is the destination node name concatenated with the stored attribute name. Every check runs before the connection is attempted so one bad entry cannot abort the pass. Skips and failures are logged as warnings as well as returned.

Outputs pointing at a combinationShape node are dropped, matching what capture_connections records. This only catches combinationShape nodes that still exist, so data captured before that filter existed can still carry plugs on deleted nodes, which are reported as missing.

Parameters:

• entries – Entries with ‘name’, ‘input’ and ‘outputs’ keys.

• destination_nodes – Names of the nodes to receive the connections.

Returns:

Counts and details of what was connected, skipped and failed.

Return type:

ApplyResult

advBlendshapeTools.api.connections_node.export_connection_data(entries: list[dict], file_path: str) → None

Write connection entries to a JSON file.

Parameters:

• entries – Entries with ‘name’, ‘input’ and ‘outputs’ keys.

• file_path – Destination path.

Raises:

ConnectionsNodeError – If the file cannot be written.

advBlendshapeTools.api.connections_node.load_connection_data(file_path: str) → list[dict]

Read connection entries from a JSON file written by export_connection_data.

Parameters:

file_path – Path to the JSON file.

Returns:

Entries with ‘name’, ‘input’ and ‘outputs’ keys.

Return type:

list[dict]

Raises:

ConnectionsNodeError – If the file is missing, unreadable, not valid JSON, carries a version other than JSON_VERSION, or has a “connections” field that is not a list of dicts with a list “outputs” field.

Exceptions

exception advBlendshapeTools.api.connections_node.ConnectionsNodeError