"pkgutil" — Utilitaire d'extension de package
*********************************************

**Code source :** Lib/pkgutil.py

======================================================================

Ce module fournit des utilitaires pour le système d'importation, en
particulier pour la prise en charge des paquets.

class pkgutil.ModuleInfo(module_finder, name, ispkg)

   Un *n*-uplet nommé qui contient un bref résumé des informations
   d'un module.

   Nouveau dans la version 3.6.

pkgutil.extend_path(path, name)

   Étend le chemin de recherche pour les modules qui composent un
   paquet. L'usage prévu est de placer le code suivant dans le
   "__init__.py" d'un paquet :

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

   Pour chaque répertoire sur "sys.path" qui a un sous-répertoire
   correspondant au nom du paquet, ajoute le sous-répertoire au
   "__path__" du paquet. Cela est utile si l'on souhaite distribuer
   différentes parties d'un paquet logique unique dans plusieurs
   répertoires.

   Elle recherche également les fichiers "*.pkg" en commençant là où
   "*" correspond à l'argument *name*. Cette fonctionnalité est
   similaire aux fichiers "*.pth" (voir le module "site" pour plus
   d'informations), à l'exception qu'elle ne traite pas de manière
   spéciale les lignes commençant par "import". Un fichier "*.pkg" est
   fiable de facto : à part la vérification des doublons, toutes les
   entrées trouvées dans un fichier "*.pkg" sont ajoutées au chemin,
   quelle que soit leur existence sur le système de fichiers. (C'est
   une fonctionnalité.)

   Si le chemin d'entrée n'est pas une liste (comme c'est le cas pour
   les paquets figés), il est retourné tel quel. Le chemin d'entrée
   n'est pas modifié ; une copie étendue en est retournée. Les
   éléments ne sont ajoutés à la copie qu'à la fin.

   L'interpréteur estime que "sys.path" est une séquence. Les éléments
   de "sys.path" qui ne sont pas des chaînes se référant à des
   répertoires existants sont ignorés. Les éléments Unicode sur
   "sys.path" qui provoquent des erreurs lorsqu'ils sont utilisés
   comme noms de fichiers peuvent amener cette fonction à lever une
   exception (conformément au comportement de "os.path.isdir()").

class pkgutil.ImpImporter(dirname=None)

   **PEP 302** Chercheur qui enveloppe l'algorithme d'importation «
   classique » de Python.

   Si *dirname* est une chaîne, un chercheur **PEP 302** est créé pour
   rechercher ce répertoire. Si *dirname* est "None", un chercheur
   **PEP 302** est créé pour rechercher le "sys.path" actuel, ainsi
   que les modules qui sont figés ou natifs.

   Notez que "ImpImporter" ne prend actuellement pas en charge son
   utilisation en tant que placement dans "sys.meta_path".

   Obsolète depuis la version 3.3: Cette émulation n'est plus
   nécessaire, car le mécanisme d'importation standard est désormais
   entièrement conforme à la **PEP 302** et disponible dans
   "importlib".

class pkgutil.ImpLoader(fullname, file, filename, etc)

   *Loader* qui encapsule l'algorithme d'importation « classique » de
   Python.

   Obsolète depuis la version 3.3: Cette émulation n'est plus
   nécessaire, car le mécanisme d'importation standard est désormais
   entièrement conforme à la **PEP 302** et disponible dans
   "importlib".

pkgutil.find_loader(fullname)

   Récupère un *loader* de module pour le *fullname* donné.

   Il s'agit d'une surcouche de compatibilité ascendante autour de
   "importlib.util.find_spec()" qui convertit la plupart des échecs en
   "ImportError" et ne renvoie que le chargeur, plutôt que le
   "importlib.machinery.ModuleSpec" complet.

   Modifié dans la version 3.3: Mise à jour pour être basée
   directement sur "importlib" au lieu de dépendre de l'émulation
   interne de la **PEP 302** du paquet.

   Modifié dans la version 3.4: Mise à jour pour être basée sur la
   **PEP 451**

pkgutil.get_importer(path_item)

   Récupère un *finder* pour l'élément *path_item* donné.

   Le chercheur retourné est mis en cache dans
   "sys.path_importer_cache" s'il a été récemment créé par le chemin
   d'un point d'entrée.

   Le cache (ou une partie de celui-ci) peut être effacé manuellement
   si une nouvelle analyse de "sys.path_hooks" est nécessaire.

   Modifié dans la version 3.3: Mise à jour pour être basée
   directement sur "importlib" au lieu de dépendre de l'émulation
   interne de la **PEP 302** du paquet.

pkgutil.get_loader(module_or_name)

   Récupère un objet *loader* pour *module_or_name*.

   Si le module ou le paquet est accessible via le mécanisme
   d'importation normal, une encapsulation autour de la partie
   pertinente de cette mécanique est renvoyé. Renvoie "None" si le
   module ne peut pas être trouvé ou importé. Si le module nommé n'est
   pas déjà importé, son paquet contenant (le cas échéant) est importé
   afin d'établir le paquet "__path__".

   Modifié dans la version 3.3: Mise à jour pour être basée
   directement sur "importlib" au lieu de dépendre de l'émulation
   interne de la **PEP 302** du paquet.

   Modifié dans la version 3.4: Mise à jour pour être basée sur la
   **PEP 451**

pkgutil.iter_importers(fullname='')

   Génère des objets *finder* pour le nom du module donné.

   Si le nom complet contient un "'.'", les chercheurs sont pour le
   paquet contenant le nom complet, sinon ils sont enregistrés pour
   tous les chercheurs de niveau supérieur (c'est-à-dire ceux de
   "sys.meta_path" et de "sys.path_hooks").

   Si le module nommé se trouve dans un paquet, ce paquet est importé
   en tant qu'effet secondaire de l'invocation de cette fonction.

   Si aucun nom de module n'est spécifié, tous les chercheurs de
   niveau supérieur sont générés.

   Modifié dans la version 3.3: Mise à jour pour être basée
   directement sur "importlib" au lieu de dépendre de l'émulation
   interne de la **PEP 302** du paquet.

pkgutil.iter_modules(path=None, prefix='')

   Fournit des "ModuleInfo" pour tous les sous-modules sur *path* ou,
   si *path* est "None", pour tous les modules de niveau supérieur sur
   "sys.path".

   *path* doit être soit "None", soit une liste de chemins pour
   rechercher des modules.

   *prefix* est une chaîne de caractères à afficher au début de chaque
   nom de module en sortie.

   Note:

     Cela fonctionne uniquement pour un *finder* qui définit une
     méthode "iter_modules()". Cette interface n'est pas standard,
     donc le module fournit également des implémentations pour
     "importlib.machinery.FileFinder" et "zipimport.zipimporter".

   Modifié dans la version 3.3: Mise à jour pour être basée
   directement sur "importlib" au lieu de dépendre de l'émulation
   interne de la **PEP 302** du paquet.

pkgutil.walk_packages(path=None, prefix='', onerror=None)

   Fournit des "ModuleInfo" pour tous les modules de manière récursive
   sur *path* ou, si *path* est "None", tous les modules accessibles.

   *path* doit être soit "None", soit une liste de chemins pour
   rechercher des modules.

   *prefix* est une chaîne de caractères à afficher au début de chaque
   nom de module en sortie.

   Notez que cette fonction doit importer tous les *packages* (*pas*
   tous les modules !) sur le *path* donné, afin d'accéder à
   l'attribut "__path__" pour trouver les sous-modules.

   *onerror* est une fonction qui est appelée avec un argument (le nom
   du paquet qui était en cours d'importation) si une exception se
   produit lors de la tentative d'importation d'un paquet. Si aucune
   fonction *onerror* n'est fournie, les "ImportError"s sont attrapées
   et ignorées, tandis que toutes les autres exceptions sont
   propagées, mettant fin à la recherche.

   Exemples :

      # list all modules python can access
      walk_packages()

      # list all submodules of ctypes
      walk_packages(ctypes.__path__, ctypes.__name__ + '.')

   Note:

     Cela fonctionne uniquement pour un *finder* qui définit une
     méthode "iter_modules()". Cette interface n'est pas standard,
     donc le module fournit également des implémentations pour
     "importlib.machinery.FileFinder" et "zipimport.zipimporter".

   Modifié dans la version 3.3: Mise à jour pour être basée
   directement sur "importlib" au lieu de dépendre de l'émulation
   interne de la **PEP 302** du paquet.

pkgutil.get_data(package, resource)

   Obtient une ressource à partir d'un paquet.

   Ceci est une surcouche pour l'API *loader* "get_data". L'argument
   *package* doit être le nom d'un paquet, au format module standard
   ("foo.bar"). L'argument *resource* doit être sous forme d'un nom de
   fichier relatif, en utilisant "/" comme séparateur de chemin. Le
   nom du répertoire parent ".." n'est pas autorisé, pas plus qu'un
   nom racine (commençant par "/").

   La fonction renvoie une chaîne binaire qui est le contenu de la
   ressource spécifiée.

   Pour les paquets situés dans le système de fichiers, qui ont déjà
   été importés, c'est l'équivalent approximatif de :

      d = os.path.dirname(sys.modules[package].__file__)
      data = open(os.path.join(d, resource), 'rb').read()

   Si le paquet ne peut pas être localisé ou chargé, ou s'il utilise
   un *loader* qui ne prend pas en charge "get_data", alors "None" est
   retourné. En particulier, le *loader* pour les *paquets espaces de
   noms* ne prend pas en charge "get_data".

pkgutil.resolve_name(name)

   Solutionne un nom en un objet.

   Cette fonctionnalité est utilisée dans de nombreux endroits de la
   bibliothèque standard (voir bpo-12915) - et une fonctionnalité
   équivalente est également présente dans des paquets largement
   utilisés tels que Setuptools, Django et Pyramid.

   Python s'attend à ce que *name* soit une chaîne de caractères dans
   l'un des formats suivants, où W est une abréviation pour un
   identifiant Python valide et le point représente un point littéral
   dans ces pseudo-regexes :

   * "W(.W)*"

   * "W(.W)*:(W(.W)*)?"

   La première forme est destinée uniquement à assurer la
   compatibilité ascendante. Elle suppose qu'une partie du nom pointé
   est un paquet, et que le reste est un objet quelque part à
   l'intérieur de ce paquet, éventuellement niché à l'intérieur
   d'autres objets. Puisque l'endroit où le paquet s'arrête et où la
   hiérarchie des objets commence ne peut pas être déduit par
   inspection, des tentatives répétées d'importation doivent être
   effectuées avec cette forme.

   Dans la deuxième forme, l'appelant clarifie le point de division en
   fournissant un seul deux-points : le nom pointé à gauche des deux-
   points est un package à importer, et le nom pointé à droite est la
   hiérarchie d'objets à l'intérieur de ce paquet. Seule une
   importation est nécessaire dans cette forme. Si elle se termine par
   un deux-points, alors un objet module est retourné.

   La fonction renvoie un objet (qui pourrait être un module), ou
   génère l'une des exceptions suivantes :

   "ValueError" – si *name* n'est pas un format reconnu.

   "ImportError" – si une importation échoue lorsqu'elle n'aurait pas
   dû.

   "AttributeError" – Si un échec s'est produit lors du parcours de la
   hiérarchie d'objets dans le paquet importé pour accéder à l'objet
   souhaité.

   Nouveau dans la version 3.9.
