`pkgutil` — Utilitaire d'extension de package¶

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

`pkgutil` — Utilitaire d'extension de package¶

Sujet précédent

Sujet suivant

Cette page

pkgutil — Utilitaire d'extension de package¶

`pkgutil` — Utilitaire d'extension de package¶