Comment créer un package d'espace de noms en Python?

En Python, un package d'espace de noms vous permet de diffuser du code Python entre plusieurs projets. Ceci est utile lorsque vous souhaitez publier des bibliothèques associées sous forme de téléchargements séparés. Par exemple, avec les répertoires Package-1et Package-2in PYTHONPATH,

Package-1/namespace/__init__.py
Package-1/namespace/module1/__init__.py
Package-2/namespace/__init__.py
Package-2/namespace/module2/__init__.py

l'utilisateur final peut import namespace.module1et import namespace.module2.

Quelle est la meilleure façon de définir un package d'espace de noms afin que plusieurs produits Python puissent définir des modules dans cet espace de noms?

TL; DR:

Sur Python 3.3, vous n'avez rien à faire, n'en mettez tout simplement pas __init__.pydans les répertoires de vos packages d'espace de noms et cela fonctionnera. Sur la version antérieure à la version 3.3, choisissez la pkgutil.extend_path()solution plutôt que pkg_resources.declare_namespace()celle, car elle est à l'épreuve du temps et déjà compatible avec les packages d'espace de noms implicites.

Python 3.3 introduit les packages d'espace de noms implicites, voir PEP 420 .

Cela signifie qu'il existe désormais trois types d'objets qui peuvent être créés par un import foo:

• Un module représenté par un foo.pyfichier
• Un package régulier, représenté par un répertoire foocontenant un __init__.pyfichier
• Un package d'espace de noms, représenté par un ou plusieurs répertoires foosans aucun __init__.pyfichier

Les packages sont aussi des modules, mais ici je veux dire "module non-package" quand je dis "module".

Il recherche sys.pathd'abord un module ou un package standard. S'il réussit, il arrête la recherche et crée et initialise le module ou le package. S'il n'a trouvé aucun module ou package normal, mais qu'il a trouvé au moins un répertoire, il crée et initialise un package d'espace de noms.

Les modules et les packages normaux sont __file__définis sur le .pyfichier à partir duquel ils ont été créés. Les packages standard et d'espace de noms sont __path__définis sur le ou les répertoires à partir desquels ils ont été créés.

Lorsque vous le faites import foo.bar, la recherche ci-dessus se produit d'abord pour foo, puis si un package a été trouvé, la recherche barest effectuée avec foo.__path__comme chemin de recherche au lieu de sys.path. Si foo.baron trouve, fooet foo.barsont créés et initialisés.

Alors, comment se mélangent les packages standards et les packages d'espace de noms? Normalement, ce n'est pas le cas, mais l'ancienne pkgutilméthode de package d'espace de noms explicite a été étendue pour inclure des packages d'espace de noms implicites.

Si vous avez un package régulier existant qui a un __init__.pycomme ceci:

from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

... le comportement hérité consiste à ajouter tous les autres packages réguliers sur le chemin recherché à son __path__. Mais dans Python 3.3, il ajoute également des packages d'espace de noms.

Vous pouvez donc avoir la structure de répertoires suivante:

├── path1
│   └── package
│       ├── __init__.py
│       └── foo.py
├── path2
│   └── package
│       └── bar.py
└── path3
    └── package
        ├── __init__.py
        └── baz.py

... et tant que les deux __init__.pyont les extend_pathlignes (et path1, path2et path3sont dans votre sys.path) import package.foo, import package.baret import package.baztout fonctionnera.

pkg_resources.declare_namespace(__name__) n'a pas été mis à jour pour inclure les packages d'espace de noms implicites.

Il existe un module standard, appelé pkgutil , avec lequel vous pouvez «ajouter» des modules à un espace de noms donné.

Avec la structure de répertoires que vous avez fournie:

Package-1/namespace/__init__.py
Package-1/namespace/module1/__init__.py
Package-2/namespace/__init__.py
Package-2/namespace/module2/__init__.py

Vous devriez mettre ces deux lignes dans les deux Package-1/namespace/__init__.py et Package-2/namespace/__init__.py(*):

from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

(* puisque - à moins que vous n'indiquiez une dépendance entre eux - vous ne savez pas lequel d'entre eux sera reconnu en premier - voir PEP 420 pour plus d'informations)

Comme la documentation dit :

Cela ajoutera à __path__tous les sous-répertoires des répertoires du package sursys.path nommés d'après le package.

À partir de maintenant, vous devriez pouvoir distribuer ces deux packages indépendamment.

Cette section devrait être assez explicite.

En bref, insérez le code de l'espace de noms __init__.py, mettez setup.pyà jour pour déclarer un espace de noms et vous êtes libre de partir.

C'est une vieille question, mais quelqu'un a récemment commenté sur mon blog que ma publication sur les packages d'espaces de noms était toujours pertinente, alors j'ai pensé que je ferais un lien vers elle ici car elle fournit un exemple pratique de la façon de le faire:

https://web.archive.org/web/20150425043954/http://cdent.tumblr.com/post/216241761/python-namespace-packages-for-tiddlyweb

Cela renvoie à cet article pour les principaux tripes de ce qui se passe:

http://www.siafoo.net/article/77#multiple-distributions-one-virtual-package

L' __import__("pkg_resources").declare_namespace(__name__)astuce conduit à peu près à la gestion des plugins dans TiddlyWeb et semble jusqu'à présent fonctionner.

Vous avez vos concepts d'espace de noms Python à l'envers, il n'est pas possible en python de mettre des packages dans des modules. Les packages contiennent des modules et non l'inverse.

Un package Python est simplement un dossier contenant un __init__.pyfichier. Un module est tout autre fichier dans un package (ou directement sur le PYTHONPATH) qui a un.py extension. Donc, dans votre exemple, vous avez deux packages mais aucun module n'est défini. Si vous considérez qu'un package est un dossier de système de fichiers et qu'un module est un fichier, vous voyez pourquoi les packages contiennent des modules et non l'inverse.

Donc, dans votre exemple, en supposant que Package-1 et Package-2 sont des dossiers sur le système de fichiers que vous avez mis sur le chemin Python, vous pouvez avoir les éléments suivants:

Package-1/
  namespace/
  __init__.py
  module1.py
Package-2/
  namespace/
  __init__.py
  module2.py

Vous avez maintenant un package namespaceavec deux modules module1et module2. et à moins que vous n'ayez une bonne raison, vous devriez probablement mettre les modules dans le dossier et n'avoir que cela sur le chemin python comme ci-dessous:

Package-1/
  namespace/
  __init__.py
  module1.py
  module2.py