Extensions Index

Add-ons (modules supplémentaires)#

Important

Cette page fait partie des Extensions, et n’est disponible qu’à titre expérimental dans les daily builds de Blender 4.2. Veuillez activer “Extensions” dans les Experimental Preferences pour faciliter le test.

Pour obtenir des informations obsolètes sur les modules complémentaires individuels fournis avec Blender, visitez Add-ons.

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 du système «  « Extensions.

Astuce

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

Chemin des modules complémentaires défini par l’utilisateur#

Vous pouvez créer un dossier personnel pour les nouveaux modules complémentaires et configurer le chemin de vos fichiers dans la section File Paths de Preferences. Pour créer un dossier personnel pour vos scripts :

  1. Créez un dossier vide à l’emplacement de votre choix (ex. my_scripts).

  2. Ajoutez un sous-dossier à my_scripts nommé addons (il doit avoir ce nom pour que Blender le reconnaisse).

  3. Ouvrez la section File Paths de Preferences.

  4. Définissez le chemin de fichier de Scripts pour pointer sur votre dossier de scripts (par ex. my_scripts).

  5. Enregistrez les préférences et redémarrez Blender pour qu’il reconnaisse l’emplacement des nouveaux add-ons.

Désormais, quand vous installez des modules complémentaires, vous pouvez sélectionner Target Path à l’installation de scripts de tierce partie. Blender va copier les modules complémentaires nouvellement installés dans le dossier sélectionné dans vos Preferences.

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 Install legacy Add-on 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éez un fichier manifeste.

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

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

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

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

  6. N’oubliez pas de le tester minutieusement.

Note

Pour tester, il est important d’installer l’extension à partir du disque et de vérifier si tout fonctionne bien. Cela vous rapprochera le plus possible de l’expérience finale.

Extensions et Namespace (espace de nom)#

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.

Modules Python tiers#

Les extensions doivent être autonomes et, en tant que telles, doivent être accompagnées de toutes leurs dépendances.

Il n’existe actuellement aucune solution générale à ce problème, même si un support est prévu à l’aide de wheels Python.

Certaines options sont répertoriées ici :

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.

Import Wheel’s Directly

Les roues elles-mêmes peuvent entraîner des conflits de version, car différents modules complémentaires peuvent nécessiter différentes versions de la même bibliothèque.

Il existe une autre façon de charger les “wheels” qui n’affecte pas sys.modules ou sys.path. De cette façon, un module complémentaire peut charger sa propre version d’une bibliothèque externe à partir de son fichier “wheels” fourni.

Voir le module complémentaire Flamenco pour un exemple d’implémentation.

Avertissement

Bien que cette méthode fonctionne dans de nombreux cas, elle peut également échouer pour diverses raisons :

  • L’accès aux fichiers fournis avec le module échoue.

  • Les importations effectuées par le module lors de l’exécution faisant référence à ses propres modules échouent.

  • Les erreurs de correspondance entre la “wheel” et le nom du module ne sont pas prises en charge.

  • Les “wheel” qui dépendent d’autres “wheel” ne sont actuellement pas prises en charge.

  • Différentes architectures système ne sont pas prises en charge.