Python Wheels¶

Les Python wheels (*.whl) sont le moyen standard de distribuer les modules Python. Ils sont pris en charge dans Blender pour créer des Extensions Python autonomes.

Directives¶

Par convention, localisez toujours les fichiers sous ./wheels/.

Exigences¶

Les “Wheels” doivent être regroupées sans modification à partir de l'index du package Python.
Les “Wheels” doivent inclure leurs dépendances.
Les noms de fichiers des “Wheels” doivent correspondre à la spécification de la distribution binaire de Python : voir la documentation. Les Wheels téléchargées à partir de l’index des packages Python suivront cette convention.
Utilisez des barres obliques comme séparateurs de chemin lorsque vous les répertoriez sur le manifeste.

Comment regrouper les Wheels¶

Les wheels Python (*.whl) peuvent être regroupées en suivant les étapes suivantes.

Téléchargement de Wheels

Télécharger la “wheel” dans le répertoire ./wheels/.

Pour les “wheels” indépendantes de la plate-forme, cet exemple télécharge jsmin :

pip wheel jsmin -w ./wheels

Pour les “wheels” contenant des fichiers binaires compilés, les “wheels” de toutes les plates-formes prises en charge doivent être incluses :

Cet exemple télécharge pillow - le module de manipulation d’images populaire.

pip download pillow --dest ./wheels --only-binary=:all: --python-version=3.11 --platform=macosx_11_0_arm64
pip download pillow --dest ./wheels --only-binary=:all: --python-version=3.11 --platform=manylinux_2_28_x86_64
pip download pillow --dest ./wheels --only-binary=:all: --python-version=3.11 --platform=win_amd64

Les identifiants de plateforme disponibles sont répertoriés sur la page de téléchargement de Pillow.

Mise à jour du manifeste

Dans blender_manifest.toml inclure les “wheels” sous forme de liste de chemins, par exemple.

wheels = [
   "./wheels/pillow-10.3.0-cp311-cp311-macosx_11_0_arm64.whl",
   "./wheels/pillow-10.3.0-cp311-cp311-manylinux_2_28_x86_64.whl",
   "./wheels/pillow-10.3.0-cp311-cp311-win_amd64.whl",
]

Maintenant, l’installation du package extraira la “wheel” dans le répertoire propre aux site-packages de l’extension.

Exécution

Une fois l’extension installée, vous pouvez vérifier que le module est en cours de chargement en l’important dans la console Python et en affichant son emplacement :

import PIL
print(PIL.__file__)

Constructions de plate-forme¶

Les Wheels peuvent avoir un impact important sur la taille d’une extension. Pour atténuer ce problème, il est possible de créer différents fichiers zip d’extension pour chaque plateforme unique requise.

Pour cela, vous devez utiliser l’option --split-platforms de la commande build.

blender --command extension build --split-platforms

Exemple¶

Extrait du fichier manifeste :

id = "my_addon_with_wheels"
version = "1.0.0"

platforms = ["windows-x64", "macos-x64"]
wheels = [
   "./wheels/pillow-10.3.0-cp311-cp311-macosx_11_0_arm64.whl",
   "./wheels/pillow-10.3.0-cp311-cp311-manylinux_2_28_x86_64.whl",
   "./wheels/pillow-10.3.0-cp311-cp311-win_amd64.whl",
]

Fichiers générés à partir de --split-platforms :

my_addon_with_wheels-1.0.0-windows_x64.zip
my_addon_with_wheels-1.0.0-macos_x64.zip

Note

Même s’il existe une wheel Linux-uniquement, aucun fichier zip Linux n’est généré. Cela se produit parce que le champ platforms ne contient que Mac et Windows.