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: La méthode "find_spec()" des chercheurs
dans les méta-chemins a remplacé "find_module()", devenue obsolète.
Bien qu'elle continue de fonctionner comme avant, le mécanisme
d'importation essaie "find_module()" uniquement si le chercheur
n'implémente pas "find_spec()".

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

Modifié dans la version 3.12: "find_module()" a été supprimé. Utiliser
"find_spec()" à la place.


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.

L'attribut "module.__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 lors de
l'initialisation des modules au démarrage de l'interpréteur. La seule
exception est "__main__" pour lequel la valeur de "__spec__" peut être
parfois None.

Lisez "ModuleSpec" pour davantage d'informations sur le contenu du
spécificateur de module.

Ajouté dans la version 3.4.


5.4.4. l'attribut "__path__" des modules
----------------------------------------

L'attribut "__path__" doit être une *sequence* (possiblement vide) de
chaînes de caractères listant tous les emplacements où se trouvent les
sous-modules du paquet. Par définition, si un module a un attribut
"__path__" alors c'est un *paquet*

L'attribut "__path__" d'un paquet est utilisé pendant l'importation de
ses 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".

Les mêmes règles que pour "sys.path" s'appliquent au "__path__" d'un
paquet. Les "sys.path_hooks" (dont la description est donnée plus bas)
sont consultés pendant le parcours du "__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.5. 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: La méthode "module_repr()" est obsolète
depuis Python 3.4, et a été supprimée en Python 3.12 et n'est donc
plus appelée lors de la résolution du "__repr__()" d'un module.


5.4.6. 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" contient une liste de chaînes de caractères indiquant des
emplacements où chercher des modules ou des paquets. Elle est
initialisée à partir de la variable d'environnement "PYTHONPATH" et de
plusieurs autres valeurs par défaut qui dépendent de l'installation et
de l'implémentation. Les entrées de "sys.path" désignent des
répertoires du système de fichiers, des fichiers zip et possiblement
d'autres « endroits » (lisez le module "site") tels que des URL ou des
requêtes dans des bases de données où Python doit rechercher des
modules. "sys.path" ne doit contenir que des chaînes de caractères ;
tous les autres types sont ignorés.

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 stocké sous "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.

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_loader()" 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".

Modifié dans la version 3.12: "find_module()" et "find_loader()" ont
été supprimées.


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

doit 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
"find_loader()" 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.
