Plugs

Accès aux attributs d’un nœud et création de plugs dynamiques.

ClassAPI 2.0SDK

Plugs gère les attributs d’un wrapper DGNode ou d’un descendant. L’accès habituel est node.plugs.

objectPlugs

Import

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

À exécuter dans Maya avec weSkel disponible. Les types om.* désignent maya.api.OpenMaya.

Héritage et périmètre

Élément	Valeur
Classe	`Plugs`
Module	`weSkel.src.core.node.extensions.plugs_lib`
Parent direct	`object`
Nature	Gestionnaire d’attributs de nœud
Propriétés issues des specs	Aucune.

Cette fiche documente les membres définis par cette classe. Les mécanismes Python standard et les membres natifs hérités sont exclus des compteurs.

Constructeur

Plugs(node: 'DGNode') → Plugs

Paramètre	Type	Défaut
`node`	`DGNode`	obligatoire

Fournir un wrapper DGNode ou descendant, pas directement son nom ni son MObject. node.plugs fournit déjà ce gestionnaire. La construction ne crée pas de nœud. Le champ public node conserve ce wrapper ; éviter de le réaffecter après mise en cache.

Champs

Membres propres. L = lecture seule ; L/E = lecture et écriture.

Champ	Type retourné	Accès	Rôle
`node`	`DGNode`	L/E	Wrapper dont le gestionnaire expose les plugs.

node

plugs.nodeLecture / écriture

Type	Contrat
`DGNode`	Wrapper dont le gestionnaire expose les plugs.

Propriétés

Membres propres. L = lecture seule ; L/E = lecture et écriture.

Propriété	Type retourné	Accès	Rôle
`all`	`Optional[PlugArray]`	L	Inventaire de plugs mémorisé, avec compounds et éléments existants.
`locked`	`Optional[List[Tuple[str, bool]]]`	L	Liste des noms et états de verrouillage de tous les plugs inventoriés.
`keyables`	`Optional[List[Tuple[str, bool]]]`	L	Liste des noms et états keyable de tous les plugs inventoriés.
`compounds`	`Optional[PlugArray]`	L	Plugs compound de l’inventaire.
`arrays`	`Optional[PlugArray]`	L	Racines de multis de l’inventaire.
`dynamics`	`Optional[PlugArray]`	L	Attributs dynamiques de l’inventaire.
`transforms`	`Optional[PlugArray]`	L	Canaux translate, rotate, scale et shear présents dans l’inventaire.

all

plugs.allLecture seule

Type	Contrat
`Optional[PlugArray]`	Inventaire de plugs mémorisé, avec compounds et éléments existants.

L’inventaire mémorise la structure, pas les valeurs. Après un ajout ou retrait effectué hors de ce gestionnaire, appeler refresh(). Les enfants et éléments sont parcourus ; ne pas supposer que la liste contient seulement les attributs racines, ni que tous les objets d’attribut sont uniques.

locked

plugs.lockedLecture seule

Type	Contrat
`Optional[List[Tuple[str, bool]]]`	Liste des noms et états de verrouillage de tous les plugs inventoriés.

Le résultat contient les états True et False. Pour obtenir une collection filtrée de plugs, utiliser plugs.all.locked ou plugs.all.keyable après vérification que all n’est pas None. Les noms renvoyés incluent le nœud.

keyables

plugs.keyablesLecture seule

Type	Contrat
`Optional[List[Tuple[str, bool]]]`	Liste des noms et états keyable de tous les plugs inventoriés.

compounds

plugs.compoundsLecture seule

Type	Contrat
`Optional[PlugArray]`	Plugs compound de l’inventaire.

arrays

plugs.arraysLecture seule

Type	Contrat
`Optional[PlugArray]`	Racines de multis de l’inventaire.

dynamics

plugs.dynamicsLecture seule

Type	Contrat
`Optional[PlugArray]`	Attributs dynamiques de l’inventaire.

transforms

plugs.transformsLecture seule

Type	Contrat
`Optional[PlugArray]`	Canaux translate, rotate, scale et shear présents dans l’inventaire.

Méthodes

Méthodes propres.

Méthode	Type retourné	Rôle
`get`	`Optional[Plug]`	Résout un nom ou un index d’attribut ; repli sur le défaut ou un plug nul.
`find`	`PlugArray`	Recherche par motif dans les noms incluant le nœud.
`keys`	`list[str]`	Renvoie les noms des plugs inventoriés, avec leur préfixe de nœud.
`items`	`list[tuple[str, Plug]]`	Renvoie les couples nom et plug de l’inventaire.
`refresh`	`None`	Reconstruit immédiatement l’inventaire des plugs.
`rename_plug`	`Plug`	Renomme un attribut dynamique et renvoie le plug renommé.
`has_plug`	`bool`	Vérifie un nom sur le nœud, ou la non-nullité d’un MPlug fourni.
`attribute_names`	`list[str]`	Renvoie les noms des plugs, incluant le nom du nœud.
`attribute_objects`	`list[om.MObject]`	Renvoie les objets des attributs présents dans l’inventaire.
`get_attr_obj_at_index`	`om.MObject`	Résout un index physique dans la liste native d’attributs du nœud.
`get_attr_fn_at_index`	`om.MFnAttribute`	Renvoie le function set de l’attribut à cet index physique.
`of_type`	`Optional[PlugArray]`	Filtre les plugs par type ; `None` si aucun ne correspond.
`add_enum_plug`	`Plug`	Crée un attribut enum dynamique, numéroté à partir de zéro.
`add_generic_plug`	`Plug`	Crée un attribut générique dynamique.
`add_matrix_plug`	`Plug`	Crée un attribut matrice dynamique.
`add_message_plug`	`Plug`	Crée un attribut message, scalaire ou multi.
`add_numeric_plug`	`Plug`	Crée un attribut numérique avec défaut et bornes facultatives.
`add_bool_plug`	`Plug`	Crée un attribut booléen dynamique.
`add_typed_plug`	`Plug`	Crée un attribut typé ; fournir un type et des données par défaut compatibles.
`add_string_plug`	`Plug`	Crée un attribut chaîne dynamique.
`add_unit_plug`	`Plug`	Appel de création d’unité actuellement incompatible ; consulter la limite.
`ensure_matrix_plug`	`Plug`	Retrouve une matrice dynamique compatible ou la crée.
`ensure_string_plug`	`Plug`	Retrouve une chaîne dynamique compatible ou la crée.
`ensure_message_plug`	`Plug`	Retrouve un message dynamique compatible ou le crée.
`set_locked`	`None`	Affecte le verrouillage aux noms fournis, puis rafraîchit l’inventaire.
`set_keyable`	`None`	Affecte le drapeau keyable aux noms fournis, puis rafraîchit.
`set_channel_box`	`None`	Affecte le drapeau Channel Box aux noms fournis, puis rafraîchit.
`lock_all`	`None`	Verrouille les plugs inventoriés.
`unlock_all`	`None`	Déverrouille les plugs inventoriés.
`keyable_all`	`None`	Active le drapeau keyable des plugs inventoriés.
`unkeyable_all`	`None`	Désactive le drapeau keyable des plugs inventoriés.
`channel_box_all`	`None`	Active le drapeau Channel Box des plugs inventoriés.
`no_channel_box_all`	`None`	Désactive le drapeau Channel Box des plugs inventoriés.
`remove`	`None`	Supprime un attribut du nœud et rafraîchit l’inventaire.
`clear_cache`	`None`	Invalide l’inventaire ; le prochain accès à `all` le reconstruira.

get

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

Paramètre	Type	Défaut
`keyname`	`Union[int, str]`	obligatoire
`default`	`Optional[Plug]`	`None`

Retour	Contrat
`Optional[Plug]`	Résout un nom ou un index d’attribut ; repli sur le défaut ou un plug nul.

Un nom absent ou un index invalide renvoie le défaut non nul fourni, sinon un Plug nul. Le retour ordinaire de plugs["absent"] est en revanche None. Les index entiers sont les positions natives des attributs du nœud, pas les indices logiques d’un multi.

find

plugs.find(pattern: str, where: str='attr')Méthode

Paramètre	Type	Défaut
`pattern`	`str`	obligatoire
`where`	`str`	`'attr'`

Retour	Contrat
`PlugArray`	Recherche par motif dans les noms incluant le nœud.

Même en mode where="attr", la recherche porte sur un nom incluant le nœud. Utiliser par exemple "*scaleX". Les modes permis sont "attr", "long" et "short" ; mode invalide : ValueError si l’inventaire n’est pas vide.

keys

plugs.keys(mode: str='attr')Méthode

Paramètre	Type	Défaut
`mode`	`str`	`'attr'`

Retour	Contrat
`list[str]`	Renvoie les noms des plugs inventoriés, avec leur préfixe de nœud.

Ces résultats incluent le préfixe de nœud, malgré les noms attr ou attribute_names. keys("attr") utilise long_name ; items("attr") utilise le nom natif name(). Pour un nom sans nœud, lire plug.long_attribute_name.

items

plugs.items(mode: str='attr')Méthode

Paramètre	Type	Défaut
`mode`	`str`	`'attr'`

Retour	Contrat
`list[tuple[str, Plug]]`	Renvoie les couples nom et plug de l’inventaire.

refresh

plugs.refresh()Méthode

Retour	Contrat
`None`	Reconstruit immédiatement l’inventaire des plugs.

rename_plug

plugs.rename_plug(old_name: str, new_name: str, *, force_refresh: bool=True)Méthode

Paramètre	Type	Défaut
`old_name`	`str`	obligatoire
`new_name`	`str`	obligatoire
`force_refresh`	`bool`	`True`

Retour	Contrat
`Plug`	Renomme un attribut dynamique et renvoie le plug renommé.

Réservé aux attributs dynamiques. Nom absent, nom de destination occupé ou attribut natif : ValueError. Le nom long et le nom court deviennent tous deux new_name. force_refresh=False évite la reconstruction immédiate de l’inventaire.

has_plug

plugs.has_plug(plug: Union[str, om.MPlug])Méthode

Paramètre	Type	Défaut
`plug`	`Union[str, om.MPlug]`	obligatoire

Retour	Contrat
`bool`	Vérifie un nom sur le nœud, ou la non-nullité d’un MPlug fourni.

Avec un str, résout l’attribut sur le nœud géré. Avec un om.MPlug, teste seulement sa non-nullité : cela ne prouve pas son appartenance à ce nœud.

attribute_names

plugs.attribute_names(*, short: bool=True)Méthode

Paramètre	Type	Défaut
`short`	`bool`	`True`

Retour	Contrat
`list[str]`	Renvoie les noms des plugs, incluant le nom du nœud.

attribute_objects

plugs.attribute_objects()Méthode

Retour	Contrat
`list[om.MObject]`	Renvoie les objets des attributs présents dans l’inventaire.

get_attr_obj_at_index

plugs.get_attr_obj_at_index(index: int)Méthode

Paramètre	Type	Défaut
`index`	`int`	obligatoire

Retour	Contrat
`om.MObject`	Résout un index physique dans la liste native d’attributs du nœud.

get_attr_fn_at_index

plugs.get_attr_fn_at_index(index: int)Méthode

Paramètre	Type	Défaut
`index`	`int`	obligatoire

Retour	Contrat
`om.MFnAttribute`	Renvoie le function set de l’attribut à cet index physique.

of_type

plugs.of_type(attr_types: Set[int])Méthode

Paramètre	Type	Défaut
`attr_types`	`Set[int]`	obligatoire

Retour	Contrat
`Optional[PlugArray]`	Filtre les plugs par type ; `None` si aucun ne correspond.

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)Méthode

Paramètre	Type	Défaut
`long_name`	`str`	obligatoire
`short_name`	`Optional[str]`	`None`
`enum_names`	`Optional[List[str]]`	`None`
`default_value`	`Optional[int]`	`None`

Retour	Contrat
`Plug`	Crée un attribut enum dynamique, numéroté à partir de zéro.

short_name=None reprend le nom long. default_value=None devient 0 ; les champs de enum_names sont numérotés 0, 1, 2…. L’inventaire est rafraîchi après création.

add_generic_plug

plugs.add_generic_plug(long_name: str, short_name: Optional[str]=None)Méthode

Paramètre	Type	Défaut
`long_name`	`str`	obligatoire
`short_name`	`Optional[str]`	`None`

Retour	Contrat
`Plug`	Crée un attribut générique dynamique.

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)Méthode

Paramètre	Type	Défaut
`long_name`	`str`	obligatoire
`short_name`	`Optional[str]`	`None`
`plug_type`	`Optional[int]`	`None`
`nice_name`	`Optional[str]`	`None`
`categories`	`Optional[Iterable[str]]`	`None`

Retour	Contrat
`Plug`	Crée un attribut matrice dynamique.

Type par défaut : om.MFnMatrixAttribute.kDouble. Le nom court reprend le nom long si omis. nice_name et categories ajoutent des métadonnées d’attribut ; aucun défaut de matrice personnalisé n’est accepté par cette signature.

add_message_plug

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

Paramètre	Type	Défaut
`long_name`	`str`	obligatoire
`short_name`	`Optional[str]`	`None`
`array`	`bool`	`False`
`index_matters`	`Optional[bool]`	`None`

Retour	Contrat
`Plug`	Crée un attribut message, scalaire ou multi.

index_matters n’est permis qu’avec array=True (ValueError sinon). False crée un multi de destination non lisible. Un ensure vérifie la forme multi et le flag demandé sans réécrire un attribut incompatible.

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)Méthode

Paramètre	Type	Défaut
`long_name`	`str`	obligatoire
`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`

Retour	Contrat
`Plug`	Crée un attribut numérique avec défaut et bornes facultatives.

short_name=None reprend le nom long. Le type numérique par défaut est om.MFnNumericData.kDouble, ou kBoolean pour add_bool_plug. Le défaut de valeur est zéro ; les bornes ne sont appliquées que si renseignées.

add_bool_plug

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

Paramètre	Type	Défaut
`long_name`	`str`	obligatoire
`short_name`	`Optional[str]`	`None`
`default_value`	`Optional[bool]`	`None`

Retour	Contrat
`Plug`	Crée un attribut booléen dynamique.

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)Méthode

Paramètre	Type	Défaut
`long_name`	`str`	obligatoire
`short_name`	`Optional[str]`	`None`
`typed_type`	`Union[int, om.MTypeId, om.MFnData, None]`	`None`
`default_value`	`Optional[Any]`	`None`

Retour	Contrat
`Plug`	Crée un attribut typé ; fournir un type et des données par défaut compatibles.

Le défaut typed_type=None choisit om.MFnData.kNumeric, mais le défaut de données est une chaîne : cet appel sans type explicite échoue dans les Maya testés. Pour un tableau typé, fournir son om.MFnData et un objet de données om.MObject compatible ; une liste Python n’est pas automatiquement convertie. Pour une chaîne, préférer add_string_plug().

add_string_plug

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

Paramètre	Type	Défaut
`long_name`	`str`	obligatoire
`short_name`	`Optional[str]`	`None`
`default_value`	`Optional[str]`	`None`

Retour	Contrat
`Plug`	Crée un attribut chaîne dynamique.

Sans valeur explicite, crée une chaîne vide. Le nom court reprend le nom long si omis. Utiliser ensure_string_plug() si l’attribut peut déjà exister.

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)Méthode

Paramètre	Type	Défaut
`long_name`	`str`	obligatoire
`short_name`	`Optional[str]`	`None`
`unit_type`	`Optional[int]`	`None`
`default_value`	`Optional[float]`	`None`

Retour	Contrat
`Plug`	Appel de création d’unité actuellement incompatible ; consulter la limite.

Limite reproduite en Maya 2025.3 et 2026.3 : TypeError. Le chemin courant transmet quatre arguments à la création native. Ce constructeur d’attribut n’est pas présenté comme opérationnel ; les plugs d’unité déjà existants restent lisibles via 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)Méthode

Paramètre	Type	Défaut
`long_name`	`str`	obligatoire
`short_name`	`Optional[str]`	`None`
`plug_type`	`Optional[int]`	`None`
`nice_name`	`Optional[str]`	`None`
`categories`	`Optional[Iterable[str]]`	`None`

Retour	Contrat
`Plug`	Retrouve une matrice dynamique compatible ou la crée.

Un attribut existant doit être dynamique et compatible ; sinon RuntimeError, sans remplacement automatique. Les paramètres de nom court ne servent qu’à la création. Un ensure n’écrase pas une valeur ou une connexion existante.

ensure_string_plug

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

Paramètre	Type	Défaut
`long_name`	`str`	obligatoire
`short_name`	`Optional[str]`	`None`
`default_value`	`Optional[str]`	`None`

Retour	Contrat
`Plug`	Retrouve une chaîne dynamique compatible ou la crée.

ensure_message_plug

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

Paramètre	Type	Défaut
`long_name`	`str`	obligatoire
`short_name`	`Optional[str]`	`None`
`array`	`bool`	`False`
`index_matters`	`Optional[bool]`	`None`

Retour	Contrat
`Plug`	Retrouve un message dynamique compatible ou le crée.

set_locked

plugs.set_locked(names: Sequence[str], state: bool)Méthode

Paramètre	Type	Défaut
`names`	`Sequence[str]`	obligatoire
`state`	`bool`	obligatoire

Retour	Contrat
`None`	Affecte le verrouillage aux noms fournis, puis rafraîchit l’inventaire.

set_keyable

plugs.set_keyable(names: Sequence[str], state: bool)Méthode

Paramètre	Type	Défaut
`names`	`Sequence[str]`	obligatoire
`state`	`bool`	obligatoire

Retour	Contrat
`None`	Affecte le drapeau keyable aux noms fournis, puis rafraîchit.

set_channel_box

plugs.set_channel_box(names: Sequence[str], state: bool)Méthode

Paramètre	Type	Défaut
`names`	`Sequence[str]`	obligatoire
`state`	`bool`	obligatoire

Retour	Contrat
`None`	Affecte le drapeau Channel Box aux noms fournis, puis rafraîchit.

lock_all

plugs.lock_all()Méthode

Retour	Contrat
`None`	Verrouille les plugs inventoriés.

unlock_all

plugs.unlock_all()Méthode

Retour	Contrat
`None`	Déverrouille les plugs inventoriés.

keyable_all

plugs.keyable_all()Méthode

Retour	Contrat
`None`	Active le drapeau keyable des plugs inventoriés.

unkeyable_all

plugs.unkeyable_all()Méthode

Retour	Contrat
`None`	Désactive le drapeau keyable des plugs inventoriés.

channel_box_all

plugs.channel_box_all()Méthode

Retour	Contrat
`None`	Active le drapeau Channel Box des plugs inventoriés.

no_channel_box_all

plugs.no_channel_box_all()Méthode

Retour	Contrat
`None`	Désactive le drapeau Channel Box des plugs inventoriés.

remove

plugs.remove(name: Union[str, om.MPlug])Méthode

Paramètre	Type	Défaut
`name`	`Union[str, om.MPlug]`	obligatoire

Retour	Contrat
`None`	Supprime un attribut du nœud et rafraîchit l’inventaire.

Noms absents et plugs nuls sont ignorés. La suppression effective utilise Maya et peut refuser un attribut natif ou non supprimable. Fournir un plug appartenant au nœud géré ; aucune validation de propriété n’est ajoutée pour un MPlug externe.

clear_cache

plugs.clear_cache()Méthode

Retour	Contrat
`None`	Invalide l’inventaire ; le prochain accès à `all` le reconstruira.

Accès Python

Expression	Retour	Comportement
`plugs["attribute"]`	`Plug \| None`	Nom long, alias court ou chemin indexé ; `None` si absent.
`len(plugs)`	`int`	Taille de l’inventaire `all`, ou zéro.
`for plug in plugs`	`Iterator[Plug]`	Parcourt l’inventaire courant.

Comportements à retenir

all mémorise l’inventaire. Après une modification structurelle externe, appeler refresh() ; pour différer ce recalcul, appeler clear_cache(). Les valeurs lues via chaque plug restent live.

Les méthodes add_* créent immédiatement des attributs. Les ensure_* réutilisent uniquement un attribut dynamique compatible, sans migration implicite. Aucun de ces appels ne garantit à lui seul une commande Undo utilisateur.

Exemple d’utilisation

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)

Résultat attendu : Plugs: PASS. Les nœuds temporaires sont supprimés dans finally.

Voir aussi : Plug · PlugArray.