# 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: Use of `find_module()` by the import system now raises `ImportWarning`.

Modifié dans la version 3.12: `find_module()` has been removed. Use `find_spec()` instead.

## 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)
    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.

Ajouté 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.

Ajouté 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.

It is strongly recommended that you rely on `__spec__` and its attributes instead of any of the other individual attributes listed below.

__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.

  It is strongly recommended that you rely on `__spec__` instead of this attribute.

  Modifié dans la version 3.12: The value of `__loader__` is expected to be the same as `__spec__.loader`. The use of `__loader__` is deprecated and slated for removal in Python 3.14.

__package__

  The module's `__package__` attribute may 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 strongly recommended that you rely on `__spec__` instead of this attribute.

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

  Modifié dans la version 3.10: `ImportWarning` is raised if import falls back to `__package__` instead of `parent`.

  Modifié dans la version 3.12: Raise `DeprecationWarning` instead of `ImportWarning` when falling back to `__package__`.

__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 `__spec__.parent` is not set, `__package__` is used as a fallback.

  Ajouté 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.

  It is strongly recommended that you rely on `__spec__` instead of `__cached__`.

### 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.12: Use of `module_repr()`, having been deprecated since Python 3.4, was removed in Python 3.12 and is no longer called during the resolution of a module's repr.

### 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.

The path based finder iterates over every entry in the search path, and for each of these, looks for an appropriate path entry finder (`PathEntryFinder`) for the path entry. Because this can be an expensive operation (e.g. there may be `stat()` call overheads for this search), the path based finder maintains a cache mapping path entries to path entry finders. This cache is maintained in `sys.path_importer_cache` (despite the name, this cache actually stores finder objects rather than being limited to importer objects). In this way, the expensive search for a particular path entry location's path entry finder need only be done once. User code is free to remove cache entries from `sys.path_importer_cache` forcing the path based finder to perform the path entry search again.

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.

To indicate to the import machinery that the spec represents a namespace portion, the path entry finder sets `submodule_search_locations` to a list containing the portion.

Modifié dans la version 3.4: `find_spec()` replaced `find_loader()` and `find_module()`, both of which are now deprecated, but will be used if `find_spec()` is not defined.

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.

`find_loader()` takes one argument, the fully qualified name of the module being imported. `find_loader()` returns a 2-tuple where the first item is the loader and the second item is a namespace portion.

À 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: Calls to `find_module()` and `find_loader()` by the import system will raise `ImportWarning`.

Modifié dans la version 3.12: `find_module()` and `find_loader()` have been removed.

## 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.

PEP 420 introduced namespace packages for Python 3.3. PEP 420 also introduced the `find_loader()` protocol as an alternative to `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.