3.17 `imp` --- Accès à l'intérieur de `import`

Ce module fournit une interface vers les mécanismes utilisés pour implémenter l'instruction import. Il définit les constantes et fonctions suivantes:

get_magic()

Retourne la valeur de la "chaîne magique" utilisée pour reconnaître les fichiers compilés (fichiers .pyc). (Cette valeur peut être différente selon les versions de Python.)

get_suffixes()

Retourne une liste de triplets, chacun décrivant un type de module particulier. Chaque triplet est de la forme

(suffixe, mode,
type)

, où suffixe est une chaîne de caractères à ajouter au nom de module pour former le nom de fichier à rechercher, mode est la chaîne de caractères décrivant le mode à passer à la fonction intégrée open() pour ouvrir le fichier (peut prendre pour valeurs 'r' pour les fichiers texte ou 'rb' pour les fichiers binaires), et type est le type de fichier, qui prend une des valeurs PY_SOURCE, PY_COMPILED, ou C_EXTENSION, décrites ci-dessous.

find_module(nom[, chemin])

Essaie de trouver le module nom sur le chemin chemin. Si chemin est une liste de noms de répertoires, chaque répertoire est examiné pour rechercher des fichiers ayant l'extension retournée par la fonction get_suffixes() ci-dessus. Les noms invalides dans cette liste sont ignorés sans provoquer d'erreur (mais tous les éléments de la liste doivent être des chaînes de caractères). Si chemin est omis ou vaut None, on cherche dans la liste de répertoires donnée par sys.path, mais en commençant par chercher dans un certain nombre d'endroits spéciaux: on cherche d'abord un module intégré ayant le nom donné (C_BUILTIN), puis un module gelé (PY_FROZEN), et sur certains systèmes on regarde aussi dans d'autres endroits (sur le Mac, on cherche une ressource (PY_RESOURCE); sous Windows, on cherche dans le registre qui peut pointer vers un fichier spécifique).

Si la recherche aboutit, la valeur renvoyée est un triplet (fichier, chemin, description) où fichier est objet fichier ouvert et positionné au début, chemin est le nom du chemin où le fichier a été trouvé et description est un triplet de la forme retournée par get_suffixes() décrivant le type de module trouvé. Si le module ne se trouve pas dans un fichier, fichier vaut None, chemin est la chaîne vide, et le triplet description contient des chaînes vides pour le suffixe et le mode; le type de module est celui indiqué entre parenthèses ci-dessus. Si la recherche n'aboutit pas, ImportError est déclenchée. D'autres exceptions indiquent des problèmes d'arguments ou d'environnement.

Cette fonction ne gère pas les noms de modules hiérarchiques (les noms qui contiennent des points). Pour trouver P.M, c'est-à-dire le sous-module M du package P, utilisez find_module() et load_module() pour trouver et charger le package P, et ensuite utilisez find_module() en donnant à l'argument chemin la valeur P.__path__. Si P a lui-même un nom à points, appliquez le principe récursivement.

load_module(nom, fichier, nomfichier, description)

Charge un module qui a été prélablement trouvé par find_module() (ou par une recherche réalisée par d'autres moyens mais qui produit des résultats compatibles). Cette fonction fait plus qu'importer un module: si le module était déjà importé, elle équivaut à reload()! L'argument nom indique le nom complet du module (y compris le nom de package, s'il s'agit d'un sous-module d'un package). L'argument fichier est un objet fichier ouvert, et nomfichier est le nom de fichier correspondant; ils peuvent valoir respectivement None et '', quand le module n'est pas chargé depuis un fichier. L'argument description est un tuple, tel qu'il serait retourné par get_suffixes(), décrivant quel type de module doit être chargé.

Si le chargement réussit, la valeur de retour est l'objet module; sinon, une exception (habituellement ImportError) est déclenchée.

Important: l'appelant doit fermer le fichier fourni en argument, s'il n'avait pas la valuer None, même quand une exception est déclenchée. Pour cela le mieux est d'utiliser un ensemble try ... finally.

new_module(nom)

Retourne un nouvel obje module vide appelé nom. Cet objet n'est pas inséré dans sys.modules.

Les constantes suivantes à valeurs entières, définies dans ce module, sont utilisées pour indiquer le résultat de la recherche réalisée par find_module().

PY_SOURCE

Le module a été trouvé dans un fichier source.

PY_COMPILED

Le module a été trouvé dans un objet fichier de code compilé.

C_EXTENSION

Le module a été trouvé dans une bibliothèque partagée chargeable dynamiquement.

PY_RESOURCE

Le module a été trouvé dans une ressource Macintosh. Cette valeur ne peut être retournée que sur un Macintosh.

PKG_DIRECTORY

Le module trouvé est un répertoire de package.

C_BUILTIN

Le module trouvé est un module intégré.

PY_FROZEN

Le module trouvé est un module gelé (voir init_frozen()).

Les constantes et fonctions suivantes sont obsolètes; leurs fonctionnalités sont disponibles via find_module() ou load_module(). Elles sont conservées pour des raisons de compatibilité ascendante:

SEARCH_ERROR

Inutilisé.

init_builtin(nom)

Initialise le module intégré appelé nom and retourne son objet module. Si le module était déjà initialisé, il sera initialisé de nouveau. Quelques modules ne peuvent pas être initialisés deux fois --- quand on essaye de les réinitialiser, une exception ImportError est déclenchée. S'il n'y a pas de module intégré appelé nom, None est retourné.

init_frozen(nom)

Initialise le module gelé appelé nom et retourne son objet module. Si le module était déjà initialisé, il sera initialisé de nouveau. S'il n'y a pas de module gelé appelé nom, None est retourné. (Les modules gelés sont des modules écrits en Python dont le code-objet compilé est incorporé dans un interpréteur Python personnalisé en utilisant l'utilitaire freeze. Voir Tools/freeze/ pour plus d'informations.)

is_builtin(nom)

Retourne 1 s'il existe un module intégré appelé nom qui peut être réinitialisé ; -1 s'il existe un module intégré appelé nom qui ne peut pas être réinitialisé (voir init_builtin()) ; 0 s'il n'existe pas de module intégré appelé nom.

is_frozen(nom)

Retourne 1 s'il existe un module gelé (voir init_frozen()) appelé nom, ou 0 s'il n'en existe pas.