imp — Access theimport internals¶

Source code:Lib/imp.py

This module provides an interface to the mechanisms used to implement theimport statement. It defines the following constants and functions:

imp.get_magic()¶

Return the magic string value used to recognize byte-compiled code files(.pyc files). (This value may be different for each Python version.)

Deprecated since version 3.4:Useimportlib.util.MAGIC_NUMBER instead.

imp.get_suffixes()¶

Return a list of 3-element tuples, each describing a particular type ofmodule. Each triple has the form(suffix,mode,type), wheresuffix isa string to be appended to the module name to form the filename to searchfor,mode is the mode string to pass to the built-inopen() functionto open the file (this can be'r' for text files or'rb' for binaryfiles), andtype is the file type, which has one of the valuesPY_SOURCE,PY_COMPILED, orC_EXTENSION, describedbelow.

Deprecated since version 3.3:Use the constants defined onimportlib.machinery instead.

imp.find_module(name[,path])¶

Try to find the modulename. Ifpath is omitted orNone, the list ofdirectory names given bysys.path is searched, but first a few specialplaces are searched: the function tries to find a built-in module with thegiven name (C_BUILTIN), then a frozen module (PY_FROZEN),and on some systems some other places are looked in as well (on Windows, itlooks in the registry which may point to a specific file).

Otherwise,path must be a list of directory names; each directory issearched for files with any of the suffixes returned byget_suffixes()above. Invalid names in the list are silently ignored (but all list itemsmust be strings).

If search is successful, the return value is a 3-element tuple(file,pathname,description):

file is an openfile object positioned at the beginning,pathnameis the pathname of the file found, anddescription is a 3-element tuple ascontained in the list returned byget_suffixes() describing the kind ofmodule found.

If the module is built-in or frozen thenfile andpathname are bothNoneand thedescription tuple contains empty strings for its suffix and mode;the module type is indicated as given in parentheses above. If the searchis unsuccessful,ImportError is raised. Other exceptions indicateproblems with the arguments or environment.

If the module is a package,file isNone,pathname is the packagepath and the last item in thedescription tuple isPKG_DIRECTORY.

This function does not handle hierarchical module names (names containingdots). In order to findP.M, that is, submoduleM of packageP, usefind_module() andload_module() to find and load packageP, andthen usefind_module() with thepath argument set toP.__path__.WhenP itself has a dotted name, apply this recipe recursively.

Deprecated since version 3.3:Useimportlib.util.find_spec() instead unless Python 3.3compatibility is required, in which case useimportlib.find_loader(). For example usage of the former case,see theExamples section of theimportlibdocumentation.

imp.load_module(name,file,pathname,description)¶

Load a module that was previously found byfind_module() (or by anotherwise conducted search yielding compatible results). This function doesmore than importing the module: if the module was already imported, it willreload the module! Thename argument indicates the fullmodule name (including the package name, if this is a submodule of apackage). Thefile argument is an open file, andpathname is thecorresponding file name; these can beNone and'', respectively, whenthe module is a package or not being loaded from a file. Thedescriptionargument is a tuple, as would be returned byget_suffixes(), describingwhat kind of module must be loaded.

If the load is successful, the return value is the module object; otherwise,an exception (usuallyImportError) is raised.

Important: the caller is responsible for closing thefile argument, ifit was notNone, even when an exception is raised. This is best doneusing atry …finally statement.

Deprecated since version 3.3:If previously used in conjunction withimp.find_module() thenconsider usingimportlib.import_module(), otherwise use the loaderreturned by the replacement you chose forimp.find_module(). If youcalledimp.load_module() and related functions directly with filepath arguments then use a combination ofimportlib.util.spec_from_file_location() andimportlib.util.module_from_spec(). See theExamplessection of theimportlib documentation for details of the variousapproaches.

imp.new_module(name)¶

Return a new empty module object calledname. This object isnot insertedinsys.modules.

Deprecated since version 3.4:Useimportlib.util.module_from_spec() instead.

imp.reload(module)¶

Reload a previously importedmodule. The argument must be a module object, soit must have been successfully imported before. This is useful if you haveedited the module source file using an external editor and want to try out thenew version without leaving the Python interpreter. The return value is themodule object (the same as themodule argument).

Whenreload(module) is executed:

• Python modules’ code is recompiled and the module-level code reexecuted,defining a new set of objects which are bound to names in the module’sdictionary. Theinit function of extension modules is not called a secondtime.

• As with all other objects in Python the old objects are only reclaimed aftertheir reference counts drop to zero.

• The names in the module namespace are updated to point to any new or changedobjects.

• Other references to the old objects (such as names external to the module) arenot rebound to refer to the new objects and must be updated in each namespacewhere they occur if that is desired.

There are a number of other caveats:

When a module is reloaded, its dictionary (containing the module’s globalvariables) is retained. Redefinitions of names will override the olddefinitions, so this is generally not a problem. If the new version of a moduledoes not define a name that was defined by the old version, the old definitionremains. This feature can be used to the module’s advantage if it maintains aglobal table or cache of objects — with atry statement it can testfor the table’s presence and skip its initialization if desired:

try:cacheexceptNameError:cache={}

It is legal though generally not very useful to reload built-in or dynamicallyloaded modules, except forsys,__main__ andbuiltins.In many cases, however, extension modules are not designed to be initializedmore than once, and may fail in arbitrary ways when reloaded.

If a module imports objects from another module usingfrom …import …, callingreload() for the other module does notredefine the objects imported from it — one way around this is to re-executethefrom statement, another is to useimport and qualifiednames (module.*name*) instead.

If a module instantiates instances of a class, reloading the module that definesthe class does not affect the method definitions of the instances — theycontinue to use the old class definition. The same is true for derived classes.

Changed in version 3.3:Relies on both__name__ and__loader__ being defined on the modulebeing reloaded instead of just__name__.

Deprecated since version 3.4:Useimportlib.reload() instead.

The following functions are conveniences for handlingPEP 3147 byte-compiledfile paths.

imp.cache_from_source(path,debug_override=None)¶

Return thePEP 3147 path to the byte-compiled file associated with thesourcepath. For example, ifpath is/foo/bar/baz.py the returnvalue would be/foo/bar/__pycache__/baz.cpython-32.pyc for Python 3.2.Thecpython-32 string comes from the current magic tag (seeget_tag(); ifsys.implementation.cache_tag is not defined thenNotImplementedError will be raised). By passing inTrue orFalse fordebug_override you can override the system’s value for__debug__, leading to optimized bytecode.

path need not exist.

Changed in version 3.3:Ifsys.implementation.cache_tag isNone, thenNotImplementedError is raised.

Deprecated since version 3.4:Useimportlib.util.cache_from_source() instead.

Changed in version 3.5:Thedebug_override parameter no longer creates a.pyo file.

imp.source_from_cache(path)¶

Given thepath to aPEP 3147 file name, return the associated source codefile path. For example, ifpath is/foo/bar/__pycache__/baz.cpython-32.pyc the returned path would be/foo/bar/baz.py.path need not exist, however if it does not conformtoPEP 3147 format, aValueError is raised. Ifsys.implementation.cache_tag is not defined,NotImplementedError is raised.

Changed in version 3.3:RaiseNotImplementedError whensys.implementation.cache_tag is not defined.

Deprecated since version 3.4:Useimportlib.util.source_from_cache() instead.

imp.get_tag()¶

Return thePEP 3147 magic tag string matching this version of Python’smagic number, as returned byget_magic().

Deprecated since version 3.4:Usesys.implementation.cache_tag directly startingin Python 3.3.

The following functions help interact with the import system’s internallocking mechanism. Locking semantics of imports are an implementationdetail which may vary from release to release. However, Python ensuresthat circular imports work without any deadlocks.

imp.lock_held()¶

ReturnTrue if the global import lock is currently held, elseFalse. On platforms without threads, always returnFalse.

On platforms with threads, a thread executing an import first holds aglobal import lock, then sets up a per-module lock for the rest of theimport. This blocks other threads from importing the same module untilthe original import completes, preventing other threads from seeingincomplete module objects constructed by the original thread. Anexception is made for circular imports, which by construction have toexpose an incomplete module object at some point.

Changed in version 3.3:The locking scheme has changed to per-module locks forthe most part. A global import lock is kept for some critical tasks,such as initializing the per-module locks.

Deprecated since version 3.4.

imp.acquire_lock()¶

Acquire the interpreter’s global import lock for the current thread.This lock should be used by import hooks to ensure thread-safety whenimporting modules.

Once a thread has acquired the import lock, the same thread may acquire itagain without blocking; the thread must release it once for each time it hasacquired it.

On platforms without threads, this function does nothing.

Changed in version 3.3:The locking scheme has changed to per-module locks forthe most part. A global import lock is kept for some critical tasks,such as initializing the per-module locks.

Deprecated since version 3.4.

imp.release_lock()¶

Release the interpreter’s global import lock. On platforms withoutthreads, this function does nothing.

Changed in version 3.3:The locking scheme has changed to per-module locks forthe most part. A global import lock is kept for some critical tasks,such as initializing the per-module locks.

Deprecated since version 3.4.

The following constants with integer values, defined in this module, are usedto indicate the search result offind_module().

imp.PY_SOURCE¶

The module was found as a source file.

Deprecated since version 3.3.

imp.PY_COMPILED¶

The module was found as a compiled code object file.

Deprecated since version 3.3.

imp.C_EXTENSION¶

The module was found as dynamically loadable shared library.

Deprecated since version 3.3.

imp.PKG_DIRECTORY¶

The module was found as a package directory.

Deprecated since version 3.3.

imp.C_BUILTIN¶

The module was found as a built-in module.

Deprecated since version 3.3.

imp.PY_FROZEN¶

The module was found as a frozen module.

Deprecated since version 3.3.

classimp.NullImporter(path_string)¶

TheNullImporter type is aPEP 302 import hook that handlesnon-directory path strings by failing to find any modules. Calling this typewith an existing directory or empty string raisesImportError.Otherwise, aNullImporter instance is returned.

Instances have only one method:

find_module(fullname[,path])¶

This method always returnsNone, indicating that the requested module couldnot be found.

Changed in version 3.3:None is inserted intosys.path_importer_cache instead of aninstance ofNullImporter.

Deprecated since version 3.4:InsertNone intosys.path_importer_cache instead.

importimpimportsysdef__import__(name,globals=None,locals=None,fromlist=None):# Fast path: see if the module has already been imported.try:returnsys.modules[name]exceptKeyError:pass# If any of the following calls raises an exception,# there's a problem we can't handle -- let the caller handle it.fp,pathname,description=imp.find_module(name)try:returnimp.load_module(name,fp,pathname,description)finally:# Since we may exit via an exception, close fp explicitly.iffp:fp.close()