Add-ons (modules supplémentaires)#

Les modules complémentaires (Add-ons) vous permettent d’étendre les fonctionnalités de Blender en utilisant Python. La plupart du temps, vous pouvez obtenir des modules complémentaires dans le cadre des Extensions du système.

Astuce

Si le module complémentaire n’est pas opérationnel après activation, vérifiez dans la fenêtre de la Console pour toute erreur qui a pu se produire.

Accès Internet#

Si le module complémentaire doit utiliser Internet, il doit vérifier la propriété (en lecture seule) bpy.app.online_access. Cette option est contrôlée par les Préférences, qui peuvent être remplacées via la ligne de commande (--offline-mode / --online-mode).

Pour de meilleurs messages d’erreur, vous pouvez également vérifier bpy.app.online_access_overriden, pour déterminer si les utilisateurs peuvent activer ou non Allow Online Access (Autoriser l’accès en ligne) dans les préférences.

Note

Les modules complémentaires qui suivent ce paramètre ne se connecteront à Internet que s’ils sont activés. Cependant, Blender ne peut pas empêcher les modules complémentaires tiers de violer cette règle.

Dépendances des paquets#

Pour que les modules complémentaires soient regroupés en tant qu’extensions, ils doivent être autonomes. Cela signifie qu’ils doivent être fournis avec toutes leurs dépendances. En particulier les modules Python tiers.

Il existe quelques options pour cela:

Bundle with Python Wheels.

C’est la méthode recommandée pour regrouper les dépendances.

Bundle other add-ons together.

Recommandé si un module complémentaire dépend d’un autre module complémentaire.

Assurez-vous que le module complémentaire individuel et combiné vérifie les types déjà enregistrés (opérateurs, panneaux,…). Cela évite la duplication des opérateurs et des panneaux sur l’interface si les modules complémentaires sont installés comme un paquet et individuellement.

Offre groupée avec Vendorize

Peut être utilisé comme moyen de regrouper des dépendances Python pures en tant que sous-module.

Cela présente l’avantage d’éviter les conflits de versions même si cela nécessite un certain travail pour configurer chaque package.

Stockage local#

Les modules complémentaires ne doivent pas supposer que leur propre répertoire est accessible en écriture par l’utilisateur puisque cela peut ne pas être le cas pour les dépôts “Système”. L’écriture de fichiers dans le répertoire du module complémentaire présente également l’inconvénient que la mise à niveau de l’extension supprimera tous les fichiers.

Les modules complémentaires qui ont besoin de leur propre répertoire utilisateur doivent utiliser une fonction utilitaire prévue à cet effet :

extension_directory = bpy.utils.extension_path_user(__package__, path="", create=True)

Si vous souhaitez créer des sous-répertoires, cela peut être fait avec l’argument``path``.

Ce répertoire sera conservé entre les mises à niveau mais sera supprimé si l’extension est désinstallée.

Modules complémentaires hérités vs extensions#

Avec l’introduction des extensions dans Blender 4.2, l’ancienne méthode de création de modules complémentaires est considérée comme obsolète. Bien que les changements soient plutôt mineurs, ils affectent les modules complémentaires existants.

Afin de permettre un processus de transition en douceur, les modules complémentaires dits hérités continueront à être pris en charge par Blender. Ils peuvent être installés via le bouton Installation des modules complémentaires hérités dans les préférences utilisateur.

Tous les responsables de modules complémentaires sont invités à convertir les modules complémentaires qu’ils souhaitent partager, afin qu’ils résistent à l’épreuve du temps et puissent prendre en charge des fonctionnalités telles que la mise à jour à partir de la plate-forme d’extensions.

Conversion, en extension, d’un module complémentaire hérité#

  1. Créer un fichier manifeste.

  2. Supprimer les informations bl_info (elles se trouvent maintenant dans le manifeste).

  3. Remplacer toutes les références au nom du module par __package__.

  4. Effectuer toutes les importations de modules pour utiliser l’importation relative.

  5. Utiliser des wheels pour regrouper vos dépendances Python externes.

  6. N’oubliez pas de le tester minutieusement.

Note

For testing it is import to install the extension from disk and check if everything is working well. This will get you as close to the final experience as possible.

Extensions et espace de noms#

Si les modules complémentaires existants utilisaient leur nom de module pour accéder aux préférences cela pourrait conduire à un conflit de noms lorsque des extensions portant le même nom (provenant de référentiels différents) seraient installées. Pour éviter ce conflit, le nom du référentiel fait désormais partie de l’espace de noms.

Par exemple, désormais, au lieu de kitsu, le nom du module serait bl_ext.{repository_module_name}.kitsu.

Cela a quelques conséquences pour les préférences et les importations de modules.

Préférences utilisateur et __package__#

Les modules complémentaires peuvent définir leurs propres préférences et y accéder en utilisant le nom complet du module. Cela se fait en utilisant __package__.

Ceci était déjà pris en charge dans les modules complémentaires existants, mais n’est pas renforcé. En tant que tel, cela peut rompre la compatibilité ascendante.

Avant :

class KitsuPreferences(bpy.types.AddonPreferences):
    bl_idname = "kitsu"
    # ... snip ...

# Access with:
addon_prefs = bpy.context.preferences.addons["kitsu"]

Maintenant :

class KitsuPreferences(bpy.types.AddonPreferences):
    bl_idname = __package__
    # ... snip ...

# Access with:
addon_prefs = bpy.context.preferences.addons[__package__]
Sous-packages

Un module complémentaire qui définit des sous-packages (sous-répertoires avec leur propre fichier __init__.py) qui doit utiliser cet identifiant devra importer le package de niveau supérieur à l’aide d’une importation relative.

from .. import __package__ as base_package

Ensuite, base_package` peut être utilisé à la place de `__package__`. Les .. pour les importations relatives aux packages parents, les sous-sous-packages doivent utiliser ... et ainsi de suite.

Note

  • La valeur de __package__ varie selon les systèmes et ne doit donc jamais être remplacée par une chaîne littérale.

  • Les extensions ne doivent pas manipuler la valeur de __package__ car cela pourrait provoquer un comportement inattendu ou des erreurs.

Importations relatives#

avant:

from kitsu import utils

maintenant:

from . import utils

L’importation de packages dans le module complémentaire doit utiliser des chemins relatifs. Il s’agit d’une fonctionnalité Python standard et applicable uniquement aux modules complémentaires comportant plusieurs dossiers.

Ceci était déjà pris en charge dans les modules complémentaires existants, mais n’est pas renforcé. En tant que tel, cela peut rompre la compatibilité ascendante.