Actions

class BuildAction

Bases: BuildActionData

The base class for any rigging action that can run during a build.

Override run to perform the rigging operations for the action

Optionally override validate to perform operations that can check the validity of the actions properties.

property blueprint: Blueprint

Return the Blueprint being built.

extend_rig_metadata_list(key, data)

Extend a list value in the metadata of the rig being built.

Parameters:

• key (str) – The metadata key for the list

• data (list) – A list of any basic python object to add to the metadata list value

static from_action_id(action_id: str) → BuildAction | None

Create and return a BuildAction by class action_id.

static from_data(data) → BuildAction | None

Create and return a BuildAction based on the given serialized data.

This is a factory method that automatically determines the class to instance using the action id in the data.

Parameters:

data – A dict object containing serialized BuildAction data

get_logger_name()

Return the name of the logger for this BuildAction.

get_min_api_version()

Override to return the minimum Maya api version required for this BuildAction. This compares against cmds.about(api=True).

get_rig_metadata() → dict

Return all metadata on the rig being built

property logger

Return the logger to use for logging from this action. Warnings and errors will be tracked and associated with the action in the editor for visibility.

run()

Perform the main functionality of this build action. Attribute values can be accessed using self.myAttr.

run_validate()

Run the validate function and perform some other basic checks to make sure the build action is valid for use.

should_abort_on_error() → bool

Should the build be aborted if an error occurs while this action is running?

update_rig_metadata_dict(key, data)

Update a dict value in the metadata of the rig being built.

Parameters:

• key (str) – The metadata key for the list

• data (dict) – A dict of any basic python objects to update the metadata value with

validate()

Validate this build action. Can be implemented in subclasses to check the action’s attribute values and raise BuildActionErrors if anything is invalid.

validate_api_version()

Validate that the current Maya version meets the requirements for this build action

validate_attr_values()

Check each action attribute to ensure it has a valid value for its attribute type. Checks for things like missing nodes or invalid options.

class BuildActionAttribute(name: str, action_spec: BuildActionSpec | None = None, action_id: str | None = None)

Bases: object

A single attribute of a build action. Contains the attributes config as well as current value and validation logic.

When creating instances you should use BuildActionAttribute.from_spec() to ensure the appropriate subclass will be instanced based on the attributes type, since each subclass has its own validation logic, etc.

clear_value()

Clear the assigned value of this attribute, resetting it to the default value.

property config: dict

Return the config for this attribute.

property default_value: Any

Return the default value of the attribute.

classmethod from_spec(name: str, action_spec: BuildActionSpec | None = None, action_id: str | None = None) → BuildActionAttribute

Create a BuildActionAttribute object from a name and spec, using the appropriate class based on the attribute type.

get_type_default_value()

Return the default value for any attribute of this type. Does not use the config defined default.

get_value()

The current value of the attribute. Returns the default value if a different value has not been set.

is_acceptable_value(new_value)

Return true if a value is acceptable. This doesn’t mean the value won’t be invalid for some other reason, just that it’s the correct type and the attribute can be set to it.

is_known_attribute() → bool

Return true if this attribute is a known and valid attribute for a build action. Will be false if the attribute is a placeholder left behind for a missing attribute.

is_value_set()

Return true if the value of this attribute has been explicitly set, false if it is the default value.

is_value_valid() → bool

Return true if the current value of this attribute is valid. Must call validate first to check the value, call get_invalid_reason to determine why the attribute is invalid if applicable.

validate()

Validate the attribute, checking its current value and other requirements and storing the reason it is invalid if applicable.

class BuildActionAttributeType

Bases: object

Constants defining the build action attribute types.

class BuildActionData(action_id: str | None = None)

Bases: object

Contains attribute values for an action to be executed during a build step.

property action_id: str

Return unique the id of the action.

add_attr(name: str) → BuildActionAttribute

Add an action attribute. Does nothing if the attribute already exists.

add_attrs(attr_names=None)

Add multiple attributes.

deserialize(data)

Set all values on this BuildActionData from data

Parameters:

data – A dict containing serialized data for this action

find_spec()

Find the action spec for this data using the current action_id.

get_attr(name: str)

Return an attribute by name.

get_attr_names() → Iterable[str]

Return a list of attribute names for this BuildAction class

get_attrs() → dict[str, BuildActionAttribute]

Return all attributes for this BuildAction class.

get_known_attrs() → dict[str, BuildActionAttribute]

Return all attributes for this BuildAction class that are known, valid attributes.

has_attr(name: str) → bool

Return True if this action data has an attribute.

has_warnings()

Return true if there are any invalid attributes or other problems with this action data.

is_missing_spec() → bool

Is there no action spec for the current action_id? This may be true if an action was renamed or not registered.

is_valid() → bool

Return True if there is a valid spec for this action

num_attrs() → int

Return the number of attributes that this BuildAction has

remove_attr(name: str)

Remove an action attribute. Does nothing if the attribute does not exist.

serialize()

Return this BuildActionData as a serialized dict object

property spec: BuildActionSpec

Return the BuildActionSpec for this action.

class BuildActionDataVariant(action_id: str | None = None, attr_names: List[str] | None = None)

Bases: BuildActionData

Contains a partial set of attribute values.

deserialize(data)

Set all values on this BuildActionData from data

Parameters:

data – A dict containing serialized data for this action

serialize()

Return this BuildActionData as a serialized dict object

exception BuildActionError

Bases: Exception

A BuildAction was misconfigured or failed during build

class BuildActionProxy(action_id=None)

Bases: BuildActionData

Acts as a stand-in for a BuildAction during Blueprint editing. Contains all attribute values for the configured action, which are used to create real BuildActions at build time.

The proxy can represent multiple BuildActions by adding ‘variants’. This allows the user to create multiple actions where only the values that are unique per variant are set, and the remaining attributes will be the same on all actions.

The proxy provides a method action_iterator which performs the actual construction of BuildActions for use at build time.

action_iterator(config: dict) → Iterable[BuildAction]

Generator that yields all the BuildActions represented by this proxy. Expands variants and builds mirrored actions if applicable.

Parameters:

config – The blueprint config.

add_variant()

Add a variant of attribute values. Does nothing if there are no variant attributes.

add_variant_attr(attr_name: str)

Add an attribute to the list of variant attributes, removing any invariant values for the attribute, and creating variant values instead.

clear_variants()

Remove all variants. Does not clear the list of variant attributes.

deserialize(data)

Set all values on this BuildActionData from data

Parameters:

data – A dict containing serialized data for this action

deserialize_variant(data: dict)

Deserialize a variant from this action’s ‘variantAttrs’ data. Injects missing information that are the same for all variants like id and attribute list.

get_color() → LinearColor

Return the color of this action when represented in the UI

get_display_name()

Return the display name of the BuildAction.

get_variant(index: int) → BuildActionDataVariant

Return the BuildActionDataVariant at an index.

get_variant_attr_names()

Return the list of all variant attribute names

get_variants() → Iterable[BuildActionDataVariant]

Return all BuildActionDataVariants in this proxy.

has_warnings()

Return true if this action has any warnings due to invalid attributes or build validation.

insert_variant(index)

Insert a variant of attribute values. Does nothing if there are no variant attributes.

Parameters:

index (int) – The index at which to insert the new variant

is_variant_action()

Returns true of this action proxy has any variant attributes.

is_variant_attr(attr_name: str)

Return True if the attribute is variant, meaning it can have a different value in each variant.

num_variants() → int

Return how many variants exist on this action proxy

remove_variant_at(index: int)

Remove a variant by index.

remove_variant_attr(attr_name: str)

Remove an attribute from the list of variant attributes, copying the value from the first variant into the default set of attr values if applicable.

serialize()

Return this BuildActionData as a serialized dict object

serialize_variant(variant: BuildActionDataVariant)

Serialize a variant for storing in this action’s data. Removes redundant information that is the same for all variants like id and attribute list.

class BuildActionRegistry

Bases: object

A registry that contains all Build Actions available for use.

add_action(action_spec: BuildActionSpec)

Add a BuildActionSpec to the registry.

find_action(action_id: str) → BuildActionSpec | None

Find a BuildActionSpec by action id

find_action_by_class(action_cls: type[BuildAction]) → BuildActionSpec | None

Find a BuildActionSpec by action class.

classmethod get()

Return the main BuildActionRegistry

get_action_ids() → Iterable[str]

Return all registered action ids.

get_action_map() → dict[str, BuildActionSpec]

Return the registered BuildActionSpecs map, indexed by action ids.

get_all_actions() → Iterable[BuildActionSpec]

Return all registered BuildActionSpecs.

remove_action(action_id)

Remove a BuildActionSpec from the registry by id.

remove_all()

Remove all actions from this registry.

class BuildActionSpec(action_cls: type[BuildAction], module)

Bases: object

Contains information about a registered build action class and its config.

property attrs

The list of all attribute definitions.

property category

The menu category where the action will be grouped.

property color

The display color of the action.

property description

The description of the action.

property display_name

The display name of the action.

property id

The globally unique action id.

is_equal(other: BuildActionSpec) → bool

Return true if this action spec is the same as another.

class BuildStep(name=None, action_proxy: BuildActionProxy | None = None, action_id: str | None = None)

Bases: object

Represents a step to perform when building a Blueprint. Steps are hierarchical, but a BuildStep that performs a BuildAction cannot have children.

action_iterator(config: dict) → Iterable[BuildAction]

Return a generator that yields all actions for this step.

Parameters:

config – The blueprint config.

add_validate_error(record: LogRecord)

Add a validation exception that was encountered when running a build validator.

child_iterator() → Iterable[BuildStep]

Generator that yields all children, recursively.

clear_validate_results()

Clear the results of the last full rig validation that was done on this step.

deserialize(data)

Load configuration of this BuildStep from data

Parameters:

data – A dict containing serialized data for this step

ensure_unique_name()

Change this step’s name to ensure that it is unique among siblings.

static from_data(data)

Return a new BuildStep instance created from serialized data.

Parameters:

data (dict) – Serialized BuildStep data

get_child_by_name(name: str) → BuildStep | None

Return a child step by name

get_child_by_path(path: str) → BuildStep | None

Return a child step by relative path

get_child_index(step: BuildStep)

Return the index of a BuildStep within this step’s list of children

get_clean_name(name: str | None) → str

Return a name for the build step, ensuring one is set if it hasn’t already been, and cleaning trailing spaces, etc.

get_color() → LinearColor

Return the color of this BuildStep when represented in the UI

get_description() → str

Return the description of this step’s action.

get_display_name() → str

Return the display name for this step.

get_full_path() → str

Return the full path to this BuildStep.

Returns:

A string path to the step e.g. ‘/MyGroupA/MyGroupB/MyBuildStep’

static get_topmost_steps(steps: List[BuildStep]) → List[BuildStep]

Return a copy of the list of BuildSteps that doesn’t include any BuildSteps that have a parent or distant parent in the list.

has_parent(step: BuildStep)

Return True if the step is an immediate or distance parent of this step.

has_warnings() → bool

Return true if this step has any validation warnings, or if its action has any warnings.

index_in_parent()

Return the index of this within its parent’s list of children.

is_disabled_in_hierarchy()

Return true if this step or any of its parents are disabled.

is_root() → bool

Return True if this is the root build step.

remove_from_parent()

Remove this item from its parent, if any.

serialize()

Return this BuildStep as a serialized dict object

set_action_proxy(action_proxy: BuildActionProxy)

Set a BuildActionProxy for this step. Will fail if the step has any children.

Parameters:

action_proxy – BuildActionProxy The new action proxy.

set_name(new_name: str | None)

Set the name of the BuildStep, modifying it if necessary to ensure that it is unique among siblings.

Parameters:

new_name (str) – The new name of the step, or None to reset the name to default.

set_name_from_action()

Set the name of the BuildStep to match the action it contains.

set_parent(new_parent: BuildStep | None)

Set the parent of this BuildStep, removing it from its old parent if necessary.