paya.lib.typeman#

WIP – unified type-checking methods for hybrid plug / value workflows.

Functions in this module expect patched PyMEL.

conform(item, distance=False, angle=False)#

Conforms to Paya types.

Parameters

distance/d (bool) – prefer Distance, Distance and Point wherever possible; defaults to False
angle/a (bool) – prefer EulerRotation, EulerRotation, Quaternion and Quaternion wherever possible; defaults to False

Raises

ValueError – The item could not be conformed to a Paya value, node, component or plug type.

Returns

The original item conformed to a Paya type.

isPyMELObject(item)#

Parameters: item – the item to inspect
Returns: True if item is an instance of a PyMEl class, otherwise False
Return type: bool

isPlug(item)#

Parameters: item – the item to inspect
Returns: True if item represents an attribute, otherwise False.
Return type: bool

isScalarValue(value)#

Parameters: value – the value to inspect
Returns: True if value is an instance of int, float, bool or Unit
Return type: bool

isScalarPlug(item)#

Parameters: item – the item to inspect
Returns: True if item is an Attribute instance, or a string representations of a scalar (1D) Maya attribute, otherwise False
Return type: bool

isScalarValueOrPlug(item)#

Parameters: item – the item to inspect
Returns: True if item represents a scalar value or plug, otherwise False.
Return type: bool

isVectorValueOrPlug(item)#

Parameters: item – the item to inspect
Returns: True if item is a vector value or attribute, otherwise False
Return type: bool

isParamVectorPair(item)#

Parameters: item – the item to inspect
Returns: True if item is a pair of scalar: vector, otherwise False

isTripleScalarValueOrPlug(item)#

Three scalar plugs in a list will not return True; they must be delivered as a numeric compound instead.

Parameters: item – the item to inspect
Returns: True if item represents a 3D vector or Euler rotation plug or value, otherwise False.
Return type: bool

conformVectorArg(arg, listLength=None)#

For methods that expect a vector argument which may also be a multi (for example upVector on distributeMatrices()). Attributes are conformed but not checked for type.

Parameters

arg (tuple | list | str, paya.runtime.data.Vector | paya.runtime.plugs.Vector, [tuple | list | str, paya.runtime.data.Vector | paya.runtime.plugs.Vector]) – strictly a single vector or a list of vectors; deeper nesting will throw an error
listLength/ll (None | int) – the preferred output length; defaults to None

Returns

A conformed vector, or list of conformed vectors.

Return type

paya.runtime.data.Vector | paya.runtime.plugs.Vector | [paya.runtime.data.Vector | paya.runtime.plugs.Vector]

describeAndConformVectorArg(vector)#

Used by methods that receive multiple forms of up vector hints in a single argument.

Parameters

vector – the argument to inspect

Raises

RuntimeError – Couldn’t parse the argument.

Returns

One of:

tuple of 'single', conformed vector value or plug
tuple of 'keys', list of conformed param, vector pairs
tuple of 'multi', list of conformed vectors

Return type

One of:

(str, paya.runtime.data.Vector | paya.runtime.plugs.Vector)
(str, [(int | float | Math1D, paya.runtime.data.Vector | paya.runtime.plugs.Vector))]
(str, [paya.runtime.data.Vector | paya.runtime.plugs.Vector])

resolveNumberOrFractionsArg(arg)#: Loosely conforms a numberOrFractions user argument. If the argument is an integer, a range of floats is returned. Otherwise, the argument is passed through without further checking.

expandVectorArgs(*args)#

Expands args, stopping at anything that looks like a vector value or plug.

Parameters: *args – the arguments to expand
Returns: The expanded arguments.

asPlug(item, quiet=False)#

If item is already an instance of Attribute, it is passed through; otherwise, it’s used to create an instance of Attribute. The advantage of checking first is that custom class assignments are preserved.

Use this form to check whether an attribute exists: bool(asPlug(item, quiet=True))

Parameters

item (str | Attribute) – the attribute instance or string
quiet (bool) – catch any errors raised when attempting to instantiate Attribute and return None; defaults to False

Returns

The attribute instance.

Return type

Attribute

asGeoPlug(item, worldSpace=None)#

Attempts to extract a geometry output plug from item.

Parameters

item (str, Geometry, Shape, Transform,) – the item to inspect
worldSpace/ws (bool) – ignored if item is a plug; specifies whether to pull the world-space or local-space output of a geometry shape or transform; if omitted, defaults to False if item is a shape, and True if it’s a transform

Raises

TypeError – Can’t extract a geo plug from item.

Returns

The geometry output.

Return type

Geometry

asCompIndexOrPlug(item)#

Used by methods which accept component arguments as indices (integers or floats) or scalar plugs (for example, NURBS curve parameter drivers), but not as instances of Component.

If item is a simple scalar type, it’s passed-through as-is. Otherwise, if it describes a Maya component, its first index is returned as a float or integer. Otherwise, an attempt is made to return it as an Attribute instance. The attribute is not checked for type.

Note

This method relies on the relevant Paya component type implementing index(), which may not always be the case.

Parameters: item – the item to conform
Raises: TypeError – Can’t parse specified item.
Returns: A scalar index / parameter value or an attribute.
Return type: int | float | Attribute

conformPlugsInArg(arg)#

Used by plugCheck. Looks for plugs recursively in an argument received by a Paya method; if any are found, they are conformed to Attribute instances.

Parameters

arg – an argument received by a Paya method

Returns

tuple of:

the original argument, with conformed plug members,
True if plugs were found, False if they weren’t

Return type

tuple

forceVectorsAsPlugs(vectors)#

If any of the provided vectors are plugs, they are passed-through as-is; those that aren’t are used as values for array attributes on a utility node, which are passed along instead.

Parameters: vectors ([list, tuple, Vector, Vector]) – the vectors to inspect
Returns: The conformed vector outputs.
Return type: [Vector]

class plugCheck(*argNames)#

Decorator-with-arguments for methods that take a plug keyword argument which defaults to None, meaning its behaviour will depend on whether any incoming arguments are plugs.

Instantiate it with a list of argument names; when the function is called, if plug still resolves as None, the arguments will be checked for plugs, and the plug keyword overriden to True where necessary before delegating to the original function. As a bonus, any plug arguments will be conformed to Attribute instances.

If the plug is passed specifically by the user as True or False, the function will be called immediately–in essence the user becomes responsible for any errors thence.

Example

@plugCheck('param')
def tangentAtParam(self, param, plug=None):
    # At this point, if plug was passed-through as None, the
    # decorator will have resolved it to True / False

    if plug:
        # Run the 'hard' implementation
    else:
        # Run the 'soft' implementation

__call__(f)#: Call self as a function.