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 plate-forme 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.