5. Le système d'importation

Le code Python d'un module peut accéder à du code d'un autre module par un mécanisme qui consiste à importer cet autre module. L'instruction import est la façon la plus courante de faire appel à ce système d'importation, mais ce n'est pas la seule. Les fonctions telles que importlib.import_module() et __import__() peuvent aussi être utilisées pour mettre en œuvre le mécanisme d'importation.

L'instruction import effectue deux opérations ; elle cherche le module dont le nom a été donné puis elle lie le résultat de cette recherche à un nom dans la portée locale. L'opération de recherche de l'instruction import consiste à appeler la fonction __import__() avec les arguments adéquats. La valeur renvoyée par __import__() est utilisée pour effectuer l'opération de liaison avec le nom fourni à l'instruction import. Reportez-vous à l'instruction import pour les détails exacts de l'opération de liaison avec le nom.

Un appel direct à __import__() effectue seulement la recherche du module et, s'il est trouvé, l'opération de création du module. Bien que des effets collatéraux puissent se produire, tels que l'importation de paquets parents et la mise à jour de divers caches (y compris sys.modules), il n'y a que l'instruction import qui déclenche l'opération de liaison avec le nom.

Quand une instruction import est exécutée, la fonction native __import__() est appelée. D'autres mécanismes d'appel au système d'importation (tels que importlib.import_module()) peuvent choisir d'ignorer __import__() et utiliser leurs propres solutions pour implémenter la sémantique d'importation.

Quand un module est importé pour la première fois, Python recherche le module et, s'il est trouvé, crée un objet module [1] en l'initialisant. Si le module n'est pas trouvé, une ModuleNotFoundError est levée. Python implémente plusieurs stratégies pour rechercher le module d'un nom donné quand le mécanisme d'importation est invoqué. Ces stratégies peuvent être modifiées et étendues par divers moyens décrits dans les sections suivantes.

Modifié dans la version 3.3: le système d'importation a été mis à jour pour implémenter complètement la deuxième partie de la PEP 302. Il n'existe plus de mécanisme implicite d'importation (le système d'importation complet est exposé via sys.meta_path). En complément, la gestion des paquets dans l'espace des noms natif a été implémentée (voir la PEP 420).

5.1. importlib

Le module importlib fournit une API riche pour interagir avec le système d'importation. Par exemple, importlib.import_module() fournit une API (que nous vous recommandons) plus simple que la fonction native __import__() pour mettre en œuvre le mécanisme d'importation. Reportez-vous à la documentation de la bibliothèque importlib pour obtenir davantage de détails.

5.2. Les paquets

Python ne connait qu'un seul type d'objet module et tous les modules sont donc de ce type, que le module soit implémenté en Python, en C ou quoi que ce soit d'autre. Pour aider à l'organisation des modules et fournir une hiérarchie des noms, Python développe le concept de paquets.

Vous pouvez vous représenter les paquets comme des répertoires dans le système de fichiers et les modules comme des fichiers dans ces répertoires. Mais ne prenez pas trop cette analogie au pied de la lettre car les paquets et les modules ne proviennent pas obligatoirement du système de fichiers. Dans le cadre de cette documentation, nous utilisons cette analogie bien pratique des répertoires et des fichiers. Comme les répertoires du système de fichiers, les paquets sont organisés de manière hiérarchique et les paquets peuvent eux-mêmes contenir des sous-paquets ou des modules.

Il est important de garder à l'esprit que tous les paquets sont des modules mais que tous les modules ne sont pas des paquets. Formulé autrement, les paquets sont juste un certain type de modules. Spécifiquement, tout module qui contient un attribut __path__ est réputé être un paquet.

Tous les modules ont un nom. Les noms des sous-paquets sont séparés du nom du paquet parent par un point (.), à l'instar de la syntaxe standard d'accès aux attributs en Python. Ainsi, vous pouvez avoir un paquet nommé email qui possède un sous-paquet nommé email.mime et un module dans ce sous-paquet nommé email.mime.text.

5.2.1. Paquets classiques

Python définit deux types de paquets, les paquets classiques et les paquets espaces de nommage. Les paquets classiques sont les paquets traditionnels tels qu'ils existaient dans Python 3.2 et antérieurs. Un paquet classique est typiquement implémenté sous la forme d'un répertoire contenant un fichier __init__.py. Quand un paquet classique est importé, ce fichier __init__.py est implicitement exécuté.

Par exemple, l'arborescence suivante définit un paquet parent au niveau le plus haut avec trois sous-paquets :

parent/
    __init__.py
    one/
        __init__.py
    two/
        __init__.py
    three/
        __init__.py

Importer parent.one exécute implicitement parent/__init__.py et parent/one/__init__.py. Les importations postérieures de parent.two ou parent.three respectivement exécutent parent/two/__init__.py ou parent/three/__init__.py respectivement.

5.2.2. Paquets espaces de nommage

Un paquet-espace de nommage est la combinaison de plusieurs portions où chaque portion fournit un sous-paquet au paquet parent. Les portions peuvent être situées à différents endroits du système de fichiers. Les portions peuvent aussi être stockées dans des fichiers zip, sur le réseau ou à tout autre endroit dans lequel Python cherche pendant l'importation. Les paquets-espaces de nommage peuvent correspondre directement à des objets du système de fichiers, ou pas ; ils peuvent être des modules virtuels qui n'ont aucune représentation concrète.

Les paquets-espaces de nommage n'utilisent pas une liste ordinaire pour leur attribut __path__. Ils utilisent en lieu et place un type itérable personnalisé qui effectue automatiquement une nouvelle recherche de portions de paquets à la tentative suivante d'importation dans ce paquet si le chemin de leur paquet parent (ou sys.path pour les paquets de plus haut niveau) change.

Pour les paquets-espaces de nommage, il n'existe pas de fichier parent/__init__.py. En fait, il peut y avoir plusieurs répertoires parent trouvés pendant le processus d'importation, où chacun est apporté par une portion différente. Ainsi, parent/one n'est pas forcément physiquement à côté de parent/two. Dans ce cas, Python crée un paquet-espace de nommage pour le paquet de plus haut niveau parent dès que lui ou l'un de ses sous-paquet est importé.

Voir aussi la PEP 420 pour les spécifications des paquets-espaces de nommage.

5.3. Recherche

Pour commencer la recherche, Python a besoin du nom qualifié du module (ou du paquet, mais ici cela ne fait pas de différence) que vous souhaitez importer. Le nom peut être donné en argument à l'instruction import ou comme paramètre aux fonctions importlib.import_module() ou __import__().

Le nom est utilisé dans plusieurs phases de la recherche et peut être un chemin séparé par des points pour un sous-module, par exemple truc.machin.bidule. Dans ce cas, Python essaie d'abord d'importer truc puis truc.machin et enfin truc.machin.bidule. Si n'importe laquelle des importations intermédiaires échoue, une ModuleNotFoundError est levée.

5.3.1. Cache des modules

Le premier endroit vérifié pendant la recherche d'une importation est sys.modules. Ce tableau de correspondances est utilisé comme cache de tous les modules déjà importés, y compris les chemins intermédiaires. Ainsi, si truc.machin.bidule a déjà été importé, sys.modules contient les entrées correspondantes à truc, truc.machin et truc.machin.bidule. À chaque chemin correspond une clé.

Pendant l'importation, le nom de module est cherché dans sys.modules et, s'il est trouvé, la valeur associée est le module recherché et le processus est fini. Cependant, si la valeur est None, alors une ModuleNotFoundError est levée. Si le nom du module n'est pas trouvé, Python continue la recherche du module.

sys.modules est accessible en lecture-écriture. Supprimer une clé peut ne pas détruire le module associé (car d'autres modules contiennent possiblement des références vers ce module), mais cela invalide l'entrée du cache pour ce nom de module. Python cherche alors un nouveau module pour ce nom. La clé peut aussi être assignée à None de manière à forcer une ModuleNotFoundError lors de la prochaine importation du module.

Attention cependant : s'il reste une référence à l'objet module et que vous invalidez l'entrée dans le cache de sys.modules puis ré-importez le module, les deux objets modules ne seront pas les mêmes. À l'inverse, importlib.reload() ré-utilise le même objet module et ré-initialise simplement le contenu du module en ré-exécutant le code du module.

5.3.2. Chercheurs et chargeurs

Si le module n'est pas trouvé dans sys.modules, alors Python utilise son protocole d'importation pour chercher et charger le module. Ce protocole se compose de deux objets conceptuels : les chercheurs et les chargeurs. Le travail du chercheur consiste à trouver, à l'aide de différentes stratégies, le module dont le nom a été fourni. Les objets qui implémentent ces deux interfaces sont connus sous le vocable « importateurs » (ils renvoient une référence vers eux-mêmes quand ils trouvent un module qui répond aux attentes).

Python inclut plusieurs chercheurs et importateurs par défaut. Le premier sait comment trouver les modules natifs et le deuxième sait comment trouver les modules figés. Un troisième chercheur recherche les modules dans import path. import path est une énumération sous forme de liste de chemins ou de fichiers zip. Il peut être étendu pour rechercher aussi dans toute ressource qui dispose d'un identifiant pour la localiser, une URL par exemple.

Le mécanisme d'importation est extensible, vous pouvez donc ajouter de nouveaux chercheurs pour étendre le domaine de recherche des modules.

Les chercheurs ne chargent pas les modules. S'il trouve le module demandé, un chercheur renvoie un spécificateur de module, qui contient toutes les informations nécessaires pour importer le module ; celui-ci sera alors utilisé par le mécanisme d'importation pour charger le module.

Les sections suivantes décrivent plus en détail le protocole utilisé par les chercheurs et les chargeurs, y compris la manière de les créer et les enregistrer pour étendre le mécanisme d'importation.

Modifié dans la version 3.4: dans les versions précédentes de Python, les chercheurs renvoyaient directement les chargeurs. Dorénavant, ils renvoient des spécificateurs de modules qui contiennent les chargeurs. Les chargeurs sont encore utilisés lors de l'importation mais ont moins de responsabilités.

5.3.3. Points d'entrées automatiques pour l'importation

Le mécanisme d'importation est conçu pour être extensible ; vous pouvez y insérer des points d'entrée automatique (hooks en anglais). Il existe deux types de points d'entrée automatique pour l'importation : les méta-points d'entrée et les points d'entrée sur le chemin des importations.

Les méta-points d'entrée sont appelés au début du processus d'importation, juste après la vérification dans le cache sys.modules mais avant tout le reste. Cela permet aux méta-points d'entrée de surcharger le traitement effectué sur sys.path, les modules figés ou même les modules natifs. L'enregistrement des méta-points d'entrée se fait en ajoutant de nouveaux objets chercheurs à sys.meta_path, comme décrit ci-dessous.

Les points d'entrée sur le chemin des importations sont appelés pendant le traitement de sys.path (ou package.__path__), au moment où le chemin qui leur correspond est atteint. Les points d'entrée sur le chemin des importations sont enregistrés en ajoutant de nouveaux appelables à sys.path_hooks, comme décrit ci-dessous.

5.3.4. Méta-chemins

Quand le module demandé n'est pas trouvé dans sys.modules, Python recherche alors dans sys.meta_path qui contient une liste d'objets chercheurs dans des méta-chemins. Ces chercheurs sont interrogés dans l'ordre pour voir s'ils savent prendre en charge le module passé en paramètre. Les chercheurs dans les méta-chemins implémentent une méthode find_spec() qui prend trois arguments : un nom, un chemin d'importation et (optionnellement) un module cible. Un chercheur dans les méta-chemins peut utiliser n'importe quelle stratégie pour déterminer s'il est apte à prendre en charge le module.

Si un chercheur dans les méta-chemins sait prendre en charge le module donné, il renvoie un objet spécificateur. S'il ne sait pas, il renvoie None. Si le traitement de sys.meta_path arrive à la fin de la liste sans qu'aucun chercheur n'a renvoyé un objet spécificateur, alors une ModuleNotFoundError est levée. Toute autre exception levée est simplement propagée à l'appelant, mettant fin au processus d'importation.

La méthode find_spec() des chercheurs dans les méta-chemins est appelée avec deux ou trois arguments. Le premier est le nom complètement qualifié du module à importer, par exemple truc.machin.bidule. Le deuxième argument est l'ensemble des chemins dans lesquels chercher. Pour les modules de plus haut niveau, le deuxième argument est None mais pour les sous-modules ou les paquets, le deuxième argument est la valeur de l'attribut __path__ du paquet parent. Si l'attribut __path__ approprié n'est pas accessible, une ModuleNotFoundError est levée. Le troisième argument est un objet module existant qui va être la cible du chargement (plus tard). Le système d'importation ne passe le module cible en paramètre que lors d'un rechargement.

Le méta-chemin peut être parcouru plusieurs fois pour une seule requête d'importation. Par exemple, si nous supposons qu'aucun des modules concernés n'a déjà été mis en cache, importer truc.machin.bidule effectue une première importation au niveau le plus haut, en appelant c_m_c.find_spec("truc", None, None) pour chaque chercheur dans les méta-chemins (c_m_c). Après que truc a été importé, truc.machin est importé en parcourant le méta-chemin une deuxième fois, appelant c_m_c.find_spec("truc.machin", truc.__path__, None). Une fois truc.machin importé, le parcours final appelle c_m_c.find_spec("truc.machin.bidule", truc.machin.__path__, None).

Quelques chercheurs dans les méta-chemins ne gèrent que les importations de plus haut niveau. Ces importateurs renvoient toujours None si on leur passe un deuxième argument autre que None.

Le sys.meta_path de Python comprend trois chercheurs par défaut : un qui sait importer les modules natifs, un qui sait importer les modules figés et un qui sait importer les modules depuis un chemin des importations (c'est le chercheur dans path).

Modifié dans la version 3.4: The find_spec() method of meta path finders replaced find_module(), which is now deprecated. While it will continue to work without change, the import machinery will try it only if the finder does not implement find_spec().

Modifié dans la version 3.10: l'utilisation de find_module() par le système d'importation lève maintenant un ImportWarning.

5.4. Chargement

Quand un spécificateur de module est trouvé, le mécanisme d'importation l'utilise (et le chargeur qu'il contient) pour charger le module. Voici à peu près ce qui se passe au sein de l'importation pendant la phase de chargement :

module = None
if spec.loader is not None and hasattr(spec.loader, 'create_module'):
    # It is assumed 'exec_module' will also be defined on the loader.
    module = spec.loader.create_module(spec)
if module is None:
    module = ModuleType(spec.name)
# The import-related module attributes get set here:
_init_module_attrs(spec, module)

if spec.loader is None:
    # unsupported
    raise ImportError
if spec.origin is None and spec.submodule_search_locations is not None:
    # namespace package
    sys.modules[spec.name] = module
elif not hasattr(spec.loader, 'exec_module'):
    module = spec.loader.load_module(spec.name)
    # Set __loader__ and __package__ if missing.
else:
    sys.modules[spec.name] = module
    try:
        spec.loader.exec_module(module)
    except BaseException:
        try:
            del sys.modules[spec.name]
        except KeyError:
            pass
        raise
return sys.modules[spec.name]

Notez les détails suivants :

• S'il existe un objet module dans sys.modules avec le même nom, import l'aurait déjà renvoyé.

• Le module existe dans sys.modules avant que le chargeur exécute le code du module. C'est crucial car le code du module peut (directement ou indirectement) s'importer lui-même ; l'ajouter à sys.modules avant évite les récursions infinies dans le pire cas et le chargement multiple dans le meilleur des cas.

• Si le chargement échoue, le module en cause (et seulement ce module) est enlevé de sys.modules. Tout module déjà dans le cache de sys.modules et tout module qui a été chargé avec succès par effet de bord doit rester dans le cache. C'est différent dans le cas d'un rechargement où même le module qui a échoué est conservé dans sys.modules.

• Après que le module est créé mais avant son exécution, le mécanisme d'importation définit les attributs relatifs à l'importation (_init_module_attrs dans l'exemple de pseudo-code ci-dessus), comme indiqué brièvement dans une section que nous abordons ensuite.

• L'exécution du module est le moment clé du chargement dans lequel l'espace de nommage du module est peuplé. L'exécution est entièrement déléguée au chargeur qui doit décider ce qui est peuplé et comment.

• Le modulé créé pendant le chargement et passé à exec_module() peut ne pas être celui qui est renvoyé à la fin de l'importation [2].

Modifié dans la version 3.4: le système d'importation a pris en charge les responsabilités des chargeurs. Celles-ci étaient auparavant effectuées par la méthode importlib.abc.Loader.load_module().

5.4.1. Chargeurs

Les chargeurs de modules fournissent la fonction critique du chargement : l'exécution du module. Le mécanisme d'importation appelle la méthode importlib.abc.Loader.exec_module() avec un unique argument, l'objet module à exécuter. Toute valeur renvoyée par exec_module() est ignorée.

Les chargeurs doivent satisfaire les conditions suivantes :

• Si le module est un module Python (par opposition aux modules natifs ou aux extensions chargées dynamiquement), le chargeur doit exécuter le code du module dans l'espace des noms globaux du module (module.__dict__).

• Si le chargeur ne peut pas exécuter le module, il doit lever une ImportError, alors que toute autre exception levée durant exec_module() est propagée.

Souvent, le chercheur et le chargeur sont le même objet ; dans ce cas, la méthode find_spec() doit juste renvoyer un spécificateur avec le chargeur défini à self.

Les chargeurs de modules peuvent choisir de créer l'objet module pendant le chargement en implémentant une méthode create_module(). Elle prend un argument, l'objet spécificateur du module et renvoie le nouvel objet du module à utiliser pendant le chargement. Notez que create_module() n'a besoin de définir aucun attribut sur l'objet module. Si cette méthode renvoie None, le mécanisme d'importation crée le nouveau module lui-même.

Nouveau dans la version 3.4: la méthode create_module() des chargeurs.

Modifié dans la version 3.4: la méthode load_module() a été remplacée par exec_module() et le mécanisme d'import assume toutes les responsabilités du chargement.

Par compatibilité avec les chargeurs existants, le mécanisme d'importation utilise la méthode load_module() des chargeurs si elle existe et si le chargeur n'implémente pas exec_module(). Cependant, load_module() est déclarée obsolète et les chargeurs doivent implémenter exec_module() à la place.

La méthode load_module() doit implémenter toutes les fonctionnalités de chargement décrites ci-dessus en plus de l'exécution du module. Toutes les contraintes s'appliquent aussi, avec quelques précisions supplémentaires :

• S'il y a un objet module existant avec le même nom dans sys.modules, le chargeur doit utiliser le module existant (sinon, importlib.reload() ne fonctionnera pas correctement). Si le module considéré n'est pas trouvé dans sys.modules, le chargeur doit créer un nouvel objet module et l'ajouter à sys.modules.

• Le module doit exister dans sys.modules avant que le chargeur n'exécute le code du module, afin d'éviter les récursions infinies ou le chargement multiple.

• Si le chargement échoue, le chargeur ne doit enlever de sys.modules que le (ou les) module ayant échoué et seulement si le chargeur lui-même a chargé le module explicitement.

Modifié dans la version 3.5: un avertissement DeprecationWarning est levé quand exec_module() est définie mais create_module() ne l'est pas.

Modifié dans la version 3.6: une exception ImportError est levée quand exec_module() est définie mais create_module() ne l'est pas.

Modifié dans la version 3.10: l'utilisation de load_module() lève un ImportWarning.

5.4.2. Sous-modules

Quand un sous-module est chargé, quel que soit le mécanisme (par exemple avec les instructions import, import-from ou avec la fonction native __import__()), une liaison est créée dans l'espace de nommage du module parent vers l'objet sous-module. Par exemple, si le paquet spam possède un sous-module foo, après l'importation de spam.foo, spam possède un attribut foo qui est lié au sous-module. Supposons que nous ayons l'arborescence suivante :

spam/
    __init__.py
    foo.py

et que le contenu de spam/__init__.py contienne :

from .foo import Foo

alors exécuter les lignes suivantes crée des liens vers foo et Foo dans le module spam :

>>> import spam
>>> spam.foo
<module 'spam.foo' from '/tmp/imports/spam/foo.py'>
>>> spam.Foo
<class 'spam.foo.Foo'>

Connaissant la façon habituelle dont Python effectue les liens, cela peut sembler surprenant. Mais c'est en fait une fonctionnalité fondamentale du système d'importation. Si vous avez quelque part sys.modules['spam'] et sys.modules['spam.foo'] (comme dans c'est le cas ci-dessus après l'importation), alors le dernier doit apparaître comme l'attribut foo du premier.

5.4.3. Spécificateurs de modules

Le mécanisme d'importation utilise diverses informations de chaque module pendant l'importation, spécialement avant le chargement. La plupart de ces informations sont communes à tous les modules. Le but d'un spécificateur de module est d'encapsuler ces informations relatives à l'importation au sein de chaque module.

Utiliser un spécificateur pendant l'importation permet de transférer l'état entre les composants du système d'importation, par exemple entre le chercheur qui crée le spécificateur de module et le chargeur qui l'exécute. Surtout, cela permet au mécanisme d'importation d'effectuer toutes les opérations classiques de chargement, alors que c'était le chargeur qui en avait la responsabilité quand il n'y avait pas de spécificateur.

Le spécificateur de module est accessible par l'attribut __spec__ de l'objet module. Lisez ModuleSpec pour davantage d'informations sur le contenu du spécificateur de module.

Nouveau dans la version 3.4.

5.4.4. Attributs des modules importés

Le mécanisme d'importation renseigne ces attributs pour chaque objet module pendant le chargement, sur la base du spécificateur de module et avant que le chargeur n'exécute le module.

__name__

L'attribut __name__ doit contenir le nom complètement qualifié du module. Ce nom est utilisé pour identifier de manière non équivoque le module dans le mécanisme d'importation.

__loader__

L'attribut __loader__ doit pointer vers l'objet chargeur que le mécanisme d'importation a utilisé pour charger le module. L'utilisation principale concerne l'introspection, mais il peut être utilisé pour d'autres fonctionnalités relatives au chargement. Par exemple, obtenir des données par l'intermédiaire du chargeur.

__package__

The module's __package__ attribute must be set. Its value must be a string, but it can be the same value as its __name__. When the module is a package, its __package__ value should be set to its __name__. When the module is not a package, __package__ should be set to the empty string for top-level modules, or for submodules, to the parent package's name. See PEP 366 for further details.

This attribute is used instead of __name__ to calculate explicit relative imports for main modules, as defined in PEP 366. It is expected to have the same value as __spec__.parent.

Modifié dans la version 3.6: la valeur de __package__ devrait être la même que celle de __spec__.parent.

__spec__

L'attribut __spec__ doit contenir un lien vers le spécificateur de module qui a été utilisé lors de l'importation du module. Définir __spec__ correctement s'applique aussi pour l'initialisation des modules au démarrage de l'interpréteur. La seule exception concerne __main__ où la valeur de __spec__ est None dans certains cas.

When __package__ is not defined, __spec__.parent is used as a fallback.

Nouveau dans la version 3.4.

Modifié dans la version 3.6: __spec__.parent est utilisé par défaut quand __package__ n'est pas défini.

__path__

Si le module est un paquet (classique ou espace de nommage), l'attribut __path__ de l'objet module doit être défini. La valeur doit être un itérable mais peut être vide si __path__ n'a pas de sens dans le contexte. Si __path__ n'est pas vide, il doit produire des chaînes lorsque l'on itère dessus. Vous trouvez plus de détails sur la sémantique de __path__ plus loin ci-dessous.

Les modules qui ne sont pas des paquets ne doivent pas avoir d'attribut __path__.

__file__

__cached__

__file__ est optionnel (si elle est spécifiée, la valeur doit être une chaîne). Cela indique le chemin vers le fichier depuis lequel le module a été chargé (s'il a été chargé à partir d'un fichier) ou le chemin du fichier de la bibliothèque partagée pour les modules d'extension chargés dynamiquement depuis une bibliothèque partagée. Il se peut qu'il n'existe pas pour certains types de modules, tels que les modules C qui sont liés statiquement à l'interpréteur, où le système d'importation le laisse indéfini parce que sa sémantique serait mauvaise (par exemple, un module chargé depuis une base de données).

Si __file__ est défini, il peut être judicieux de définir l'attribut __cached__ dont la valeur est le chemin vers une version compilée du code (par exemple, le fichier bytecode). Le fichier n'a pas besoin d'exister pour définir cet attribut : le chemin peut simplement pointer vers l'endroit où le fichier compilé aurait été placé (voir la PEP 3147).

Notez que __cached__ peut être défini même si __file__ n'est pas défini. Cependant, ce scénario semble rare. Au final, c'est le chargeur qui utilise les spécifications du module fournies par le chercheur (spécifications à partir desquelles sont dérivées __file__ et __cached__). Donc, si le chargeur peut charger depuis un module mis en cache mais ne peut pas charger depuis un fichier, ce scénario a du sens.

5.4.5. module.__path__

Par définition, si un module possède un attribut __path__, c'est un paquet.

L'attribut __path__ d'un paquet est utilisé pendant l'importation des sous-paquets. Dans le mécanisme d'importation, son fonctionnement ressemble beaucoup à sys.path, c'est-à-dire qu'il fournit une liste d'emplacements où rechercher les modules pendant l'importation. Cependant, __path__ est beaucoup plus contraint que sys.path.

__path__ doit être un itérable de chaînes de caractères, mais il peut être vide. Les mêmes règles que pour sys.path s'appliquent au __path__ d'un paquet et sys.path_hooks (dont la description est donnée plus bas) est consulté pendant le parcours de __path__ du paquet.

Le fichier __init__.py d'un paquet peut définir ou modifier l'attribut __path__ d'un paquet, et c'est ainsi qu'étaient implémentés les paquets-espaces de nommage avant la PEP 420. Depuis l'adoption de la PEP 420, les paquets-espaces de nommage n'ont plus besoin d'avoir des fichiers __init__.py qui ne font que de la manipulation de __path__ ; le mécanisme d'importation définit automatiquement __path__ correctement pour un paquet-espace de nommage.

5.4.6. Représentation textuelle d'un module

Par défaut, tous les modules ont une représentation textuelle utilisable. Cependant, en utilisant les attributs définis ci-dessus et dans le spécificateur de module, vous pouvez explicitement mieux contrôler l'affichage des objets modules.

Si le module possède un spécificateur (__spec__), le mécanisme d'importation essaie de générer une représentation avec celui-ci. S'il échoue ou s'il n'y a pas de spécificateur, le système d'importation construit une représentation par défaut en utilisant toute information disponible sur le module. Il tente d'utiliser module.__name__, module.__file__ et module.__loader__ comme entrées pour la représentation, avec des valeurs par défaut lorsque l'information est manquante.

Les règles exactes utilisées sont :

• Si le module possède un attribut __spec__, la valeur est utilisée pour générer la représentation. Les attributs name, loader, origin et has_location sont consultés.

• Si le module possède un attribut __file__, il est utilisé pour construire la représentation du module.

• Si le module ne possède pas d'attribut __file__ mais possède un __loader__ qui n'est pas None, alors la représentation du chargeur est utilisée pour construire la représentation du module.

• Sinon, il utilise juste le __name__ du module dans la représentation.

Modifié dans la version 3.4: l'utilisation de loader.module_repr() est devenue obsolète et le spécificateur de module est utilisé dorénavant par le mécanisme d'importation pour générer la représentation textuelle du module.

Par compatibilité descendante avec Python 3.3, la représentation textuelle du module est générée en appelant la méthode module_repr() du chargeur, si elle est définie, avant même d'essayer l'approche décrite ci-dessus. Cependant, cette méthode est obsolète.

Modifié dans la version 3.10: l'appel à module_repr() a maintenant lieu après avoir essayé d'utiliser l'attribut __spec__ du module mais avant de se rabattre vers __file__. L'utilisation de module_repr() est prévue d'être arrêtée dans Python 3.12.

5.4.7. Invalidation de bytecode mis en cache

Avant que Python ne charge du bytecode en cache à partir d'un fichier .pyc, il vérifie si ce cache est bien à jour par rapport au fichier source .py. Python effectue cette vérification en stockant l'horodatage de la dernière modification de la source ainsi que sa taille dans le fichier cache au moment où il l'écrit. À l'exécution, le système d'importation valide le fichier cache en comparant les métadonnées que le cache contient avec les métadonnées de la source.

Python gère également les fichiers caches « avec empreintes », qui stockent une empreinte (hash en anglais) du contenu de la source plutôt que des métadonnées. Il existe deux variations des fichiers .pyc avec empreintes : vérifiés et non-vérifiés. Pour les fichiers .pyc avec empreinte vérifiés, Python valide le fichier cache en calculant l'empreinte du fichier source et compare les empreintes. Si l'empreinte stockée dans le fichier cache est invalide, Python la recalcule et écrit un nouveau fichier cache avec empreinte. Pour les fichiers .pyc avec empreinte non vérifiés, Python considère simplement que le fichier cache est valide s'il existe. La validation (ou non) des fichiers .pyc avec empreinte peut être définie avec l'option --check-hash-based-pycs.

Modifié dans la version 3.7: ajout des fichiers .pyc avec empreinte. Auparavant, Python gérait les caches de bytecode sur la base de l'horodatage.

5.5. Le chercheur dans path

Comme indiqué précédemment, Python est livré par défaut avec plusieurs chercheurs dans les méta-chemins. L'un deux, appelé chercheur dans path (PathFinder), recherche dans le chemin des importations qui contient une liste d'entrées dans path. Chaque entrée désigne un emplacement où rechercher des modules.

Le chercheur dans path en tant que tel ne sait pas comment importer quoi que ce soit. Il ne fait que parcourir chaque entrée de path et associe à chacune d'elle un « chercheur d'entrée dans path » qui sait comment gérer le type particulier de chemin considéré.

L'ensemble par défaut des « chercheurs d'entrée dans path » implémente toute la sémantique pour trouver des modules dans le système de fichiers, gérer des fichiers spéciaux tels que le code source Python (fichiers .py), le bytecode Python (fichiers .pyc) et les bibliothèques partagées (par exemple les fichiers .so). Quand le module zipimport de la bibliothèque standard le permet, les « chercheurs d'entrée dans path » par défaut savent aussi gérer tous ces types de fichiers (autres que les bibliothèques partagées) encapsulés dans des fichiers zip.

Les chemins ne sont pas limités au système de fichiers. Ils peuvent faire référence à des URL, des requêtes dans des bases de données ou tout autre emplacement qui peut être spécifié dans une chaîne de caractères.

Le chercheur dans path fournit aussi des points d'entrées (ou hooks) et des protocoles de manière à pouvoir étendre et personnaliser les types de chemins dans lesquels chercher. Par exemple, si vous voulez pouvoir chercher dans des URL réseau, vous pouvez écrire une fonction « point d'entrée » qui implémente la sémantique HTTP pour chercher des modules sur la toile. Ce point d'entrée (qui doit être un appelable) doit renvoyer un chercheur d'entrée dans path qui gère le protocole décrit plus bas et qui sera utilisé pour obtenir un chargeur de module sur la toile.

Avertissement : cette section et la précédente utilisent toutes les deux le terme chercheur, dans un cas chercheur dans les méta-chemins et dans l'autre chercheur d'entrée dans path. Ces deux types de chercheurs sont très similaires, gèrent des protocoles similaires et fonctionnent de manière semblable pendant le processus d'importation, mais il est important de garder à l'esprit qu'ils sont subtilement différents. En particulier, les chercheurs dans les méta-chemins opèrent au début du processus d'importation, comme clé de parcours de sys.meta_path.

Au contraire, les « chercheurs d'entrée dans path » sont, dans un sens, un détail d'implémentation du chercheur dans path et, en fait, si le chercheur dans path était enlevé de sys.meta_path, aucune des sémantiques des « chercheurs d'entrée dans path » ne serait invoquée.

5.5.1. Chercheurs d'entrée dans path

Le chercheur dans path (path based finder en anglais) est responsable de trouver et charger les modules et les paquets Python dont l'emplacement est spécifié par une chaîne dite d'entrée dans path. La plupart de ces entrées désignent des emplacements sur le système de fichiers, mais il n'y a aucune raison de les limiter à ça.

En tant que chercheur dans les méta-chemins, un chercheur dans path implémente le protocole find_spec() décrit précédemment. Cependant, il autorise des points d'entrée (hooks en anglais) supplémentaires qui peuvent être utilisés pour personnaliser la façon dont les modules sont trouvés et chargés depuis le chemin des importations.

Trois variables sont utilisées par le chercheur dans path : sys.path, sys.path_hooks et sys.path_importer_cache. L'attribut __path__ des objets paquets est aussi utilisé. Il permet de personnaliser encore davantage le mécanisme d'importation.

sys.path contains a list of strings providing search locations for modules and packages. It is initialized from the PYTHONPATH environment variable and various other installation- and implementation-specific defaults. Entries in sys.path can name directories on the file system, zip files, and potentially other "locations" (see the site module) that should be searched for modules, such as URLs, or database queries. Only strings should be present on sys.path; all other data types are ignored.

Le chercheur dans path est un chercheur dans les méta-chemins, donc le mécanisme d'importation commence la recherche dans le chemin des importations par un appel à la méthode find_spec() du chercheur dans path, comme décrit précédemment. Quand l'argument path de find_spec() est donné, c'est une liste de chemins à parcourir, typiquement un attribut __path__ pour une importation à l'intérieur d'un paquet. Si l'argument path est None, cela indique une importation de niveau le plus haut et sys.path est utilisée.

Le chercheur dans path itère sur chaque entrée dans le path et, pour chacune, regarde s'il trouve un chercheur d'entrée dans path (PathEntryFinder) approprié à cette entrée. Comme cette opération est coûteuse (elle peut faire appel à plusieurs appels stat() pour cela), le chercheur dans path maintient un cache de correspondance entre les entrées et les « chercheurs d'entrée dans path ». Ce cache est géré par sys.path_importer_cache (en dépit de son nom, ce cache stocke les objets chercheurs plutôt que les simples objets importateurs). Ainsi, la recherche coûteuse pour une entrée de path spécifique n'a besoin d'être effectuée qu'une seule fois par le chercheur d'entrée dans path. Le code de l'utilisateur peut très bien supprimer les entrées du cache sys.path_importer_cache, forçant ainsi le chercheur dans path à effectuer une nouvelle fois la recherche sur chaque entrée [3].

Si une entrée n'est pas présente dans le cache, le chercheur dans path itère sur chaque callable de sys.path_hooks. Chaque point d'entrée sur une entrée de path de cette liste est appelé avec un unique argument, l'entrée dans laquelle chercher. L'appelable peut soit renvoyer un chercheur d'entrée dans path apte à prendre en charge l'entrée ou lever une ImportError. Une ImportError est utilisée par le chercheur dans path pour signaler que le point d'entrée n'a pas trouvé de chercheur d'entrée dans path pour cette entrée. L'exception est ignorée et l'itération sur le chemin des importations se poursuit. Le point d'entrée doit attendre qu'on lui passe soit une chaîne de caractères soit une chaîne d'octets ; l'encodage des chaînes d'octets est à la main du point d'entrée (par exemple, ce peut être l'encodage du système de fichiers, de l'UTF-8 ou autre chose) et, si le point d'entrée n'arrive pas à décoder l'argument, il doit lever une ImportError.

Si l'itération sur sys.path_hooks se termine sans qu'aucun chercheur d'entrée dans path ne soit renvoyé, alors la méthode find_spec() du chercheur dans path stocke None dans le sys.path_importer_cache (pour indiquer qu'il n'y a pas de chercheur pour cette entrée) et renvoie None, indiquant que ce chercheur dans les méta-chemins n'a pas trouvé le module.

Si un chercheur d'entrée dans path est renvoyé par un des points d'entrée de sys.path_hooks, alors le protocole suivant est utilisé pour demander un spécificateur de module au chercheur, spécificateur qui sera utilisé pour charger le module.

Le répertoire de travail courant — noté sous la forme d'une chaîne de caractères vide — est géré d'une manière légèrement différente des autres entrées de sys.path. D'abord, si le répertoire de travail courant s'avère ne pas exister, aucune valeur n'est stockée dans sys.path_importer_cache. Ensuite, la valeur pour le répertoire de travail courant est vérifiée à chaque recherche de module. Enfin, le chemin utilisé pour sys.path_importer_cache et renvoyée par importlib.machinery.PathFinder.find_spec() est le nom réel du répertoire de travail courant et non pas la chaîne vide.

5.5.2. Protocole des chercheurs d'entrée dans path

Afin de gérer les importations de modules, l'initialisation des paquets et d'être capables de contribuer aux portions des paquets-espaces de nommage, les chercheurs d'entrée dans path doivent implémenter la méthode find_spec().

La méthode find_spec() prend deux arguments : le nom complètement qualifié du module en cours d'importation et (optionnellement) le module cible. find_spec() renvoie un spécificateur de module pleinement peuplé. Ce spécificateur doit avoir son chargeur (attribut loader) défini, à une exception près.

Pour indiquer au mécanisme d'importation que le spécificateur représente une portion d'un espace de nommage, le chercheur d'entrée dans path définit l'attribut submodule_search_locations à une liste contenant la portion.

Modifié dans la version 3.4: la méthode find_spec() remplace find_loader() et find_module(), ces deux méthodes étant dorénavant obsolètes mais restant utilisées si find_spec() n'est pas définie.

Les vieux chercheurs d'entrée dans path peuvent implémenter une des deux méthodes obsolètes à la place de find_spec(). Ces méthodes sont toujours prises en compte dans le cadre de la compatibilité descendante. Cependant, si find_spec() est implémentée par le chercheur d'entrée dans path, les méthodes historiques sont ignorées.

La méthode find_spec() prend un argument : le nom complètement qualifié du module en cours d'importation. find_loader() renvoie un couple dont le premier élément est le chargeur et le second est une portion d'espace de nommage.

À fin de compatibilité descendante avec d'autres implémentations du protocole d'importation, beaucoup de chercheurs d'entrée dans path gèrent aussi la méthode traditionnelle find_module() que l'on trouve dans les chercheurs dans les méta-chemins. Cependant, les méthodes find_module() des chercheurs d'entrée dans path ne sont jamais appelées avec un argument path (il est convenu qu'elles enregistrent les informations relatives au chemin approprié au moment de leur appel initial au point d'entrée).

La méthode find_module() des chercheurs d'entrée dans path est obsolète car elle n'autorise pas le chercheur d'entrée dans path à contribuer aux portions d'espaces de nommage des paquets-espaces de nommage. Si à la fois find_loader() et find_module() sont définies pour un chercheur d'entrée dans path, le système d'importation utilise toujours find_loader() plutôt que find_module().

Modifié dans la version 3.10: les appels à find_module() et find_loader() par le système d'importation lèvent un ImportWarning.

5.6. Remplacement du système d'importation standard

La manière la plus fiable de remplacer tout le système d'importation est de supprimer le contenu par défaut de sys.meta_path et de le remplacer complètement par un chercheur dans les méta-chemins sur mesure.

S'il convient juste de modifier le comportement de l'instruction import sans affecter les autres API qui utilisent le système d'importation, alors remplacer la fonction native __import__() peut être suffisant. Cette technique peut aussi être employée au niveau d'un module pour n'altérer le comportement des importations qu'à l'intérieur de ce module.

Pour empêcher sélectivement l'importation de certains modules par un point d'entrée placé en tête dans le méta-chemin (plutôt que de désactiver complètement le système d'importation), il suffit de lever une ModuleNotFoundError directement depuis find_spec() au lieu de renvoyer None. En effet, ce dernier indique que la recherche dans le méta-chemin peut continuer alors que la levée de l'exception termine immédiatement la recherche.

5.7. Importations relatives au paquet

Les importations relatives commencent par une suite de points. Un seul point avant indique une importation relative, démarrant avec le paquet actuel. Deux points ou plus avant indiquent une importation relative au parent du paquet actuel, un niveau par point avant le premier. Par exemple, en ayant le contenu suivant :

package/
    __init__.py
    subpackage1/
        __init__.py
        moduleX.py
        moduleY.py
    subpackage2/
        __init__.py
        moduleZ.py
    moduleA.py

Dans subpackage1/moduleX.py ou subpackage1/__init__.py, les importations suivantes sont des importations relatives valides :

from .moduleY import spam
from .moduleY import spam as ham
from . import moduleY
from ..subpackage1 import moduleY
from ..subpackage2.moduleZ import eggs
from ..moduleA import foo

Les importations absolues peuvent utiliser soit la syntaxe import <>, soit from <> import <>, mais les importations relatives doivent seulement utiliser la deuxième forme, la raison étant :

import XXX.YYY.ZZZ

devrait exposer XXX.YYY.ZZZ comme une expression utilisable, mais .moduleY n’est pas une expression valide.

5.8. Cas particulier de __main__

Le module __main__ est un cas particulier pour le système d'importation de Python. Comme indiqué par ailleurs, le module __main__ est initialisé directement au démarrage de l'interpréteur, un peu comme sys et builtins. Cependant, au contraire des deux cités précédemment, ce n'est pas vraiment un module natif. Effectivement, la manière dont est initialisé __main__ dépend des drapeaux et options avec lesquels l'interpréteur est lancé.

5.8.1. __main__.__spec__

En fonction de la manière dont __main__ est initialisé, __main__.__spec__ est défini de manière conforme ou mis à None.

Quand Python est démarré avec l'option -m, __spec__ est défini à la valeur du spécificateur du module ou paquet correspondant. Python peuple aussi __spec__ quand le module __main__ est chargé en tant que partie de l'exécution d'un répertoire, d'un fichier zip ou d'une entrée de sys.path.

Dans les autres cas, __main__.__spec__ est mis à None, car le code qui peuple __main__ ne trouve pas de correspondance directe avec un module que l'on importe :

• invite de commande interactive

• l'option -c

• lecture depuis l'entrée standard

• lecture depuis un fichier de code source ou de bytecode

Notez que __main__.__spec__ vaut toujours None dans le dernier cas, même si le fichier pourrait techniquement être importé directement en tant que module. Utilisez l'option -m si vous souhaitez disposer de métadonnées valides du module dans __main__.

Notez aussi que même quand __main__ correspond à un module importable et que __main__.__spec__ est défini en conséquence, ils seront toujours considérés comme des modules distincts. Cela est dû au fait que le bloc encadré par if __name__ == "__main__": ne s'exécute que quand le module est utilisé pour peupler l'espace de nommage de __main__, et pas durant une importation normale.

5.9. Références

Le mécanisme d'importation a considérablement évolué depuis les débuts de Python. La spécification des paquets originale est toujours disponible, bien que quelques détails ont changé depuis l'écriture de ce document.

La spécification originale de sys.meta_path se trouve dans la PEP 302. La PEP 420 contient des extensions significatives.

La PEP 420 a introduit les paquets-espaces de nommage pour Python 3.3. La PEP 420 a aussi introduit le protocole recherche du chargeur comme une alternative à find_module().

La PEP 366 décrit l'ajout de l'attribut __package__ pour les importations relatives explicites dans les modules principaux.

La PEP 328 a introduit les importations absolues et les importations relatives explicites. Elle a aussi proposé __name__ pour la sémantique que la PEP 366 attribuait à __package__.

PEP 338 définit l'exécution de modules en tant que scripts.

PEP 451 ajoute l'encapsulation dans les objets spécificateurs de l'état des importations, module par module. Elle reporte aussi la majorité des responsabilités des chargeurs vers le mécanisme d'importation. Ces changements permettent de supprimer plusieurs API dans le système d'importation et d'ajouter de nouvelles méthodes aux chercheurs et chargeurs.

Notes

[1]

Voir types.ModuleType.

[2]

L'implémentation de importlib évite d'utiliser directement la valeur de retour. À la place, elle récupère l'objet module en recherchant le nom du module dans sys.modules. L'effet indirect est que le module importé peut remplacer le module de même nom dans sys.modules. C'est un comportement spécifique à l'implémentation dont le résultat n'est pas garanti pour les autres implémentations de Python.

[3]

In legacy code, it is possible to find instances of imp.NullImporter in the sys.path_importer_cache. It is recommended that code be changed to use None instead. See Portage de code Python for more details.