Complements

Els Complements us permeten ampliar la funcionalitat del Blender a través de Python. El més habitual és que pugueu obtenir complements com a part del sistema d'Extensions.

Truc

Si el Complement no s’activa quan està habilitat, comproveu la Finestra de consola per si hi ha hagut errors.

Accés a internet

Si al complement li cal utilitzar Internet, hauríeu de comprovar la propietat (només de lectura) bpy.app.online_access. Aquesta opció ve controlada per Preferències, que es poden sobreseure via línia d’ordres (--offline-mode / --online-mode).

Per millorar els missatges d’error, també podeu comprovar bpy.app.online_access_override per determinar si les usuàries poden activar Permetre accés en línia a les preferències o no.

Nota

Els complements que segueixin aquest paràmetre només es connectaran a Internet si l’accés està habilitat. No obstant això, Blender no pot evitar que els complements de terceres violin aquesta regla.

Dependències de la compilació

Per agregar els complements com a extensions, han de ser autocontinguts. Això vol dir que han de venir amb totes les seves dependències. Sobretot els mòduls Python de terceres.

Hi ha unes quantes opcions a aquest efecte:

Compilació amb Python Wheels.

Aquesta és la manera recomanada d’empaquetar dependències.

Empaquetar altres complements junts.

Es recomana quan un complement depèn d’un altre complement.

Assegureu-vos que tant el complement individual com el combinat comproven els tipus ja registrats (operadors, plafons, …). Així s’evita la duplicació d’operadors i plafons a la interfície si els complements s’instal·len com a paquet i individualment.

Compilació amb Vendorize

Es pot utilitzar com una manera d’empaquetar dependències de python pures com a submòdul.

Té l’avantatge d’evitar conflictes de versions encara que requereixi una mica de feina per configurar cada paquet.

Magatzem local

Amb els complements no s’ha de donar per fet que el seu propi directori és escrivible per part de la usuària, ja que pot ser que això no sigui el cas amb els repositoris del «Sistema». L’escriptura de documents al directori de complements també té el costat negatiu amb el fet que, amb les actualitzacions de l’extensió, eliminarà tots els documents.

Els complements que requereixin un directori d’usuària propi han d’utilitzar una funció d’utensili expressa per a aquest propòsit:

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

Si voleu crear subdirectoris, es pot fer amb l’argument path.

Aquest directori es conservarà entre actualitzacions, però s’eliminarà si l’extensió es desinstal·la.

Complements d’extensions vs antiquats

Amb la introducció d’Extensions a Blender 4.2, la manera antiga de crear complements es considera obsoleta. Si bé els canvis són bastant petits, sí que afecten els complements existents.

Per tal de permetre un procés de transició fluid, els anomenats complements antiquats continuaran amb el suport de Blender. Es poden instal·lar amb el botó Instal·lar complement antiquat a les preferències de la usuària.

S’insta a totes les mantenidores de complements a convertir els complements que volen compartir, de manera que siguin a prova de canvis i siguin compatibles amb funcionalitats com l’actualització des de la plataforma d’extensions.

Conversió d’un Complement antiquat en una Extensió

  1. Creeu un document manifest.

  2. Suprimiu la informació bl_info (ara ja la teniu a manifest).

  3. Substituïu totes les referències al nom del mòdul a __package__.

  4. Feu que totes les importacions del mòdul utilitzin la importació relativa.

  5. Utilitzeu wheels per a empaquetar les dependències externes de Python.

  6. Recordeu de repassar-ho de dalt a baix.

Nota

Per a posar-la a prova, és important instal·lar l’extensió des del disc i comprovar si tot funciona bé. Això us acostarà al màxim possible a l’experiència final.

Extensions i espai denominatiu

Els complements antiquats utilitzarien el nom del seu mòdul per accedir a les preferències. Això podria provocar un conflicte de noms quan s’instal·lessin extensions amb el mateix nom (de diferents repositoris). Per evitar aquest conflicte, el nom del repositori ara forma part de l’espai denominatiu.

Per exemple, ara en comptes de kitsu el nom del mòdul seria bl_ext.{repository_module_name}.kitsu.

Això té algunes implicacions per a les preferències i les importacions de mòduls.

Preferències d’usuària i __package__

Els complements poden definir les seves pròpies preferències emprant el nom del paquet com a identificador. S’hi pot accedir mitjançant __package__.

Això ja estava admès amb els complements antiquats, però no s’havia reforçat, cosa que implica que es pot trencar la compatibilitat retrospectiva.

Abans:

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

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

Ara:

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

# Access with:
addon_prefs = bpy.context.preferences.addons[__package__]
Sub-paquets

Un complement que defineixi subpaquets (subdirectoris amb el seu propi document __init__.py) que necessiti utilitzar aquest identificador haurà d’importar el paquet de nivell superior mitjançant una importació relativa.

from .. import __package__ as base_package

Aleshores es pot utilitzar base_package en comptes de __package__. El .. importa relativament al pare dels paquets, els sub-subpaquets han d’utilitzar ... i així successivament.

Nota

  • El valor de __package__ variarà entre sistemes, de manera que mai no s’ha de substituir per una cadena literal.

  • Les extensions no han de manipular el valor de __package__, ja que es podria provocar un comportament inesperat o errors.

Importacions relatives

abans:

from kitsu import utils

ara:

from. import utils

La importació de paquets dins del mòdul de complements ha d’utilitzar rutes relatives. Aquesta és una característica estàndard de Python i només és aplicable per als complements que tenen múltiples carpetes.

Això ja estava admès amb els complements antiquats, però no s’havia reforçat, cosa que implica que es pot trencar la compatibilitat retrospectiva.