Python Wheels

Python Wheels (*.whl) constitueix la forma estàndard de distribuir els mòduls de python. Són compatibles amb Blender per fer Extensions de Python autocontingudes.

Pautes

  • Per convenció, localitzeu sempre els documents sota ./wheels/.

Requisits

  • Wheels s’ha de compilar sense modificar des de l'Índex de paquets python.

  • Wheels ha d’incloure les seves dependències.

  • Els noms de documents de Wheels han de conlligar amb l’especificació de distribució binària de Python: vegeu documents. Wheels baixat des de l’índex de paquets de Python seguirà aquesta convenció.

  • Empreu barres inclinades endavant com a separadors de rutes quan ho enumereu al manifest.

Com compilar Wheels

Python wheels (*.whl) es pot compilar seguint els passos següents.

Descarregar Wheels

Descarregueu el wheel al directori ./wheels/.

Per a wheels que són independents de la plataforma, aquest exemple descarrega jsmin:

pip wheel jsmin -w ./wheels

Per a wheels que contenen documents compilats binaris, s’ha d’incloure wheels per a totes les plataformes compatibles:

Aquest exemple descarrega pillow - el popular mòdul de manipulació d’imatges.

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

Els identificadors de plataforma disponibles es mostren a la pàgina de descàrregues de pillow.

Actualitzar el Manifest

A blender_manifest.toml cal incloure els wheels com a llista de rutes, p. ex.

wheels = [
   "./wheels/pillow-12.1.0-cp313-cp313-macosx_11_0_arm64.whl",
   "./wheels/pillow-12.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
   "./wheels/pillow-12.1.0-cp313-cp313-win_amd64.whl",
]

Ara la instal·lació del paquet extraurà el wheels al directori site-packages propi de les extensions.

En execució

Un cop instal·lada l’extensió, podeu comprovar si el mòdul es carrega important-lo a la consola de python i imprimint-ne la ubicació:

import PIL
print(PIL.__file__)

Compilacions de plataforma

Wheels pot afectar greument la mida d’una extensió. Per mitigar-ho, es poden crear diferents documents zip d’extensions per a cada plataforma única necessària.

Per fer-ho cal recorrer a l’opció --split-platforms des de l’ordre build.

blender --command extension build --split-platforms

Exemple

Extracte de document Manifest:

id = "my_addon_with_wheels"
version = "1.0.0"

platforms = ["windows-x64", "macos-x64"]
wheels = [
   "./wheels/pillow-12.1.0-cp313-cp313-macosx_11_0_arm64.whl",
   "./wheels/pillow-12.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
   "./wheels/pillow-12.1.0-cp313-cp313-win_amd64.whl",
]

Documents generats des de --split-platforms:

  • el_meu_complement_amb_wheels-1.0.0-windows_x64.zip

  • el_meu_complement_amb_wheels-1.0.0-macos_x64.zip

Nota

Tot i que hi ha un wheel només per a Linux, no es genera cap document zip de Linux. Això és perquè el camp platforms només té Mac i Windows.