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

Lors de l'appel à "__import__()" dans le déroulement de l'instruction
d'importation, 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 leur propre solution 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éé 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'import 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 du paquet des noms natifs a été implémenté
(voir la **PEP 420**).


5.1. "importlib"
================

Le module "importlib" fournit une API riche pour interagir avec le
système d'import. 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'import. 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 des points (*.*), à l'instar de la syntaxe
standard d'accès aux attributs en Python. Ainsi, vous pouvez avoir un
module nommé "sys" et un paquet nommé "email", qui à son tour possède
un sous-paquet nommé "email.mime" avec 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 le 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 gelé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. Ceci permet aux méta-points d'entrée de
surcharger le traitement effectué sur "sys.path", les modules gelé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'import 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
gelé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()".


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

Notez les détails suivants :

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

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

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

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

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

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

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


5.4.1. Chargeurs
----------------

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

Les chargeurs doivent satisfaire les conditions suivantes :

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

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

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

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

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

Modifié dans la version 3.4: La méthode "load_module()" a été
remplacée par "exec_module()" et le mécanisme d'import assume toutes
les responsabilités du chargement.Par compatibilité avec les chargeurs
existants, le mécanisme d'importation utilise la méthode
"load_module()" des chargeurs si elle existe et si le chargeur
n'implémente pas "exec_module()". Cependant, "load_module()" est
déclarée obsolète et les chargeurs doivent implémenter "exec_module()"
à la place.La méthode "load_module()" *doit* implémenter toutes les
fonctionnalités de chargement décrites ci-dessus en plus de
l'exécution du module. Toutes les contraintes s'appliquent aussi, avec
quelques précisions supplémentaires :

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

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

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

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

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


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
       bar.py

et que le contenu de "spam/__init__.py" soit :

   from .foo import Foo
   from .bar import Bar

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

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

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


5.4.3. Spécificateurs de modules
--------------------------------

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

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

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

Nouveau dans la version 3.4.


5.4.4. Attributs des modules importés
-------------------------------------

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

__name__

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

__loader__

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

__package__

   L'attribut "__package__" du module doit être défini. Sa valeur doit
   être une chaîne de caractères, qui peut être la même que son
   attribut "__name__". Quand le module est un paquet, la valeur de
   "__package__" doit être définie à la même valeur que son
   "__name__". Quand le module n'est pas un paquet, "__package__" doit
   être la chaîne vide pour les modules de niveau le plus haut, et le
   nom du paquet parent pour les sous-modules. Voir la **PEP 366**
   pour plus de détails.

   Cet attribut est utilisé à la place de "__name__" pour calculer les
   importations relatives explicites des modules principaux, comme
   défini dans la **PEP 366**. Il devrait avoir la même valeur que
   "__spec__.parent".

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

__spec__

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

   Quand "__package__" n'est pas défini, "__spec__.parent" est utilisé
   par défaut.

   Nouveau dans la version 3.4.

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

__path__

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

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

__file__

__cached__

   "__file__" est optionnel. S'il est défini, la valeur de cet
   attribut doit être une chaîne. Le système d'importation peut
   décider de laisser "__file__" indéfini si cela ne fait pas sens de
   le définir (par exemple, lorsqu'on charge un module 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**).

   Vous pouvez aussi définir "__cached__" quand "__file__" n'est pas
   défini. Cependant, ce scénario semble rare. Au final, c'est le
   chargeur qui utilise les valeurs de "__file__" ou "__cached__".
   Donc, si le chargeur peut charger depuis un module mis en cache
   mais ne peut pas charger depuis un fichier, ce scénario a du sens.


5.4.5. module.__path__
----------------------

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

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

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

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


5.4.6. Représentation textuelle d'un module
-------------------------------------------

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

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

Les règles exactes utilisées sont :

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

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

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

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

Modifié dans la version 3.4: L'utilisation de "loader.module_repr()"
est devenue obsolète et le spécificateur de module est utilisé
dorénavant par le mécanisme d'importation pour générer la
représentation textuelle du module.Par compatibilité descendante avec
Python 3.3, la représentation textuelle du module est générée en
appelant la méthode "module_repr()" du chargeur, si elle est définie,
avant même d'essayer l'approche décrite ci-dessus. Cependant, cette
méthode est obsolète.


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 ou
d'octets ; tous les autres types sont ignorés. L'encodage des entrées
de chaînes d'octets est déterminé par chaque *chercheur d'entrée dans
path*.

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 *stat()* pour cela),
le chercheur dans *path* maintient un cache de correspondance entre
les entrées et les "chercheurs d'entrée dans *path*". Ce cache est
géré par "sys.path_importer_cache" (en dépit de son nom, ce cache
stocke les objets chercheurs plutôt que les simples objets
*importateurs*). Ainsi, la recherche coûteuse pour une *entrée de
path* spécifique n'a besoin d'être effectuée qu'une seule fois par le
*chercheur d'entrée dans path*. Le code de l'utilisateur peut très
bien supprimer les entrées du cache "sys.path_importer_cache", forçant
ainsi le chercheur dans *path* à effectuer une nouvelle fois la
recherche sur chaque entrée [3].

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

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

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

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


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

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

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

Pour indiquer au mécanisme d'importation que le spécificateur
représente une *portion* d'un espace de nommage, le chercheur d'entrée
dans *path* définit le chargeur du spécificateur à "None" et
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. Quand le
premier élément (c'est-à-dire le chargeur) est "None", cela signifie
que, bien que le chercheur d'entrée dans *path* n'a pas de chargeur
pour le module considéré, il sait que cette entrée contribue à une
portion d'espace de nommage pour le module considéré. C'est presque
toujours le cas quand vous demandez à Python d'importer un paquet-
espace de nommage qui n'est pas présent physiquement sur le système de
fichiers. Quand un chercheur d'entrée dans *path* renvoie "None" pour
le chargeur, la valeur du second élément du couple renvoyé doit être
une séquence, éventuellement vide.Si "find_loader()" renvoie une
valeur de chargeur qui n'est pas "None", la portion est ignorée et le
chargeur est renvoyé par le chercheur dans *path*, mettant un terme à
la recherche dans les chemins.À 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()".


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, "None" 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. 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.7.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

* "-c" option

* 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.8. Idées d'amélioration
=========================

XXX Ce serait vraiment bien de disposer d'un diagramme.

XXX * ("import_machinery.rst") Pourquoi pas une section dédiée aux
attributs des modules et paquets, développant ou remplaçant les
entrées associées dans la page de référence du modèle de données ?

XXX *runpy*, *pkgutil* et autres dans le manuel de la bibliothèque
devraient comporter un lien "Lisez aussi" en début de page pointant
vers la section du nouveau mécanisme d'import.

XXX Ajouter des explications sur les différentes manières dont
"__main__" est initialisé ?

XXX Ajouter des informations sur les pièges et bizarreries de
"__main__" (c-à-d des extraits de la **PEP 395**).


5.9. Références
===============

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

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

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

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

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

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

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

-[ Notes ]-

[1] Voir "types.ModuleType".

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

[3] Dans du code historique, il est possible de trouver des instances
    de "imp.NullImporter" dans "sys.path_importer_cache". Il est
    recommandé de modifier ce code afin d'utiliser "None" à la place.
    Lisez Portage de code Python pour plus de détails.
