| \section{\module{imp} --- |
| Access the \keyword{import} internals} |
| |
| \declaremodule{builtin}{imp} |
| \modulesynopsis{Access the implementation of the \keyword{import} statement.} |
| |
| |
| This\stindex{import} module provides an interface to the mechanisms |
| used to implement the \keyword{import} statement. It defines the |
| following constants and functions: |
| |
| |
| \begin{funcdesc}{get_magic}{} |
| \indexii{file}{byte-code} |
| Return the magic string value used to recognize byte-compiled code |
| files (\file{.pyc} files). (This value may be different for each |
| Python version.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{get_suffixes}{} |
| Return a list of triples, each describing a particular type of module. |
| Each triple has the form \code{(\var{suffix}, \var{mode}, |
| \var{type})}, where \var{suffix} is a string to be appended to the |
| module name to form the filename to search for, \var{mode} is the mode |
| string to pass to the built-in \function{open()} function to open the |
| file (this can be \code{'r'} for text files or \code{'rb'} for binary |
| files), and \var{type} is the file type, which has one of the values |
| \constant{PY_SOURCE}, \constant{PY_COMPILED}, or |
| \constant{C_EXTENSION}, described below. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{find_module}{name\optional{, path}} |
| Try to find the module \var{name} on the search path \var{path}. If |
| \var{path} is a list of directory names, each directory is searched |
| for files with any of the suffixes returned by \function{get_suffixes()} |
| above. Invalid names in the list are silently ignored (but all list |
| items must be strings). If \var{path} is omitted or \code{None}, the |
| list of directory names given by \code{sys.path} is searched, but |
| first it searches a few special places: it tries to find a built-in |
| module with the given name (\constant{C_BUILTIN}), then a frozen module |
| (\constant{PY_FROZEN}), and on some systems some other places are looked |
| in as well (on the Mac, it looks for a resource (\constant{PY_RESOURCE}); |
| on Windows, it looks in the registry which may point to a specific |
| file). |
| |
| If search is successful, the return value is a triple |
| \code{(\var{file}, \var{pathname}, \var{description})} where |
| \var{file} is an open file object positioned at the beginning, |
| \var{pathname} is the pathname of the |
| file found, and \var{description} is a triple as contained in the list |
| returned by \function{get_suffixes()} describing the kind of module found. |
| If the module does not live in a file, the returned \var{file} is |
| \code{None}, \var{filename} is the empty string, and the |
| \var{description} tuple contains empty strings for its suffix and |
| mode; the module type is as indicate in parentheses above. If the |
| search is unsuccessful, \exception{ImportError} is raised. Other |
| exceptions indicate problems with the arguments or environment. |
| |
| This function does not handle hierarchical module names (names |
| containing dots). In order to find \var{P}.\var{M}, i.e., submodule |
| \var{M} of package \var{P}, use \function{find_module()} and |
| \function{load_module()} to find and load package \var{P}, and then use |
| \function{find_module()} with the \var{path} argument set to |
| \code{\var{P}.__path__}. When \var{P} itself has a dotted name, apply |
| this recipe recursively. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{load_module}{name, file, filename, description} |
| Load a module that was previously found by \function{find_module()} (or by |
| an otherwise conducted search yielding compatible results). This |
| function does more than importing the module: if the module was |
| already imported, it is equivalent to a |
| \function{reload()}\bifuncindex{reload}! The |
| \var{name} argument indicates the full module name (including the |
| package name, if this is a submodule of a package). The \var{file} |
| argument is an open file, and \var{filename} is the corresponding |
| file name; these can be \code{None} and \code{''}, respectively, when |
| the module is not being loaded from a file. The \var{description} |
| argument is a tuple as returned by \function{find_module()} describing |
| what kind of module must be loaded. |
| |
| If the load is successful, the return value is the module object; |
| otherwise, an exception (usually \exception{ImportError}) is raised. |
| |
| \strong{Important:} the caller is responsible for closing the |
| \var{file} argument, if it was not \code{None}, even when an exception |
| is raised. This is best done using a \keyword{try} |
| ... \keyword{finally} statement. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{new_module}{name} |
| Return a new empty module object called \var{name}. This object is |
| \emph{not} inserted in \code{sys.modules}. |
| \end{funcdesc} |
| |
| The following constants with integer values, defined in this module, |
| are used to indicate the search result of \function{find_module()}. |
| |
| \begin{datadesc}{PY_SOURCE} |
| The module was found as a source file. |
| \end{datadesc} |
| |
| \begin{datadesc}{PY_COMPILED} |
| The module was found as a compiled code object file. |
| \end{datadesc} |
| |
| \begin{datadesc}{C_EXTENSION} |
| The module was found as dynamically loadable shared library. |
| \end{datadesc} |
| |
| \begin{datadesc}{PY_RESOURCE} |
| The module was found as a Macintosh resource. This value can only be |
| returned on a Macintosh. |
| \end{datadesc} |
| |
| \begin{datadesc}{PKG_DIRECTORY} |
| The module was found as a package directory. |
| \end{datadesc} |
| |
| \begin{datadesc}{C_BUILTIN} |
| The module was found as a built-in module. |
| \end{datadesc} |
| |
| \begin{datadesc}{PY_FROZEN} |
| The module was found as a frozen module (see \function{init_frozen()}). |
| \end{datadesc} |
| |
| The following constant and functions are obsolete; their functionality |
| is available through \function{find_module()} or \function{load_module()}. |
| They are kept around for backward compatibility: |
| |
| \begin{datadesc}{SEARCH_ERROR} |
| Unused. |
| \end{datadesc} |
| |
| \begin{funcdesc}{init_builtin}{name} |
| Initialize the built-in module called \var{name} and return its module |
| object. If the module was already initialized, it will be initialized |
| \emph{again}. A few modules cannot be initialized twice --- attempting |
| to initialize these again will raise an \exception{ImportError} |
| exception. If there is no |
| built-in module called \var{name}, \code{None} is returned. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{init_frozen}{name} |
| Initialize the frozen module called \var{name} and return its module |
| object. If the module was already initialized, it will be initialized |
| \emph{again}. If there is no frozen module called \var{name}, |
| \code{None} is returned. (Frozen modules are modules written in |
| Python whose compiled byte-code object is incorporated into a |
| custom-built Python interpreter by Python's \program{freeze} utility. |
| See \file{Tools/freeze/} for now.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{is_builtin}{name} |
| Return \code{1} if there is a built-in module called \var{name} which |
| can be initialized again. Return \code{-1} if there is a built-in |
| module called \var{name} which cannot be initialized again (see |
| \function{init_builtin()}). Return \code{0} if there is no built-in |
| module called \var{name}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{is_frozen}{name} |
| Return \code{1} if there is a frozen module (see |
| \function{init_frozen()}) called \var{name}, or \code{0} if there is |
| no such module. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{load_compiled}{name, pathname, file} |
| \indexii{file}{byte-code} |
| Load and initialize a module implemented as a byte-compiled code file |
| and return its module object. If the module was already initialized, |
| it will be initialized \emph{again}. The \var{name} argument is used |
| to create or access a module object. The \var{pathname} argument |
| points to the byte-compiled code file. The \var{file} |
| argument is the byte-compiled code file, open for reading in binary |
| mode, from the beginning. |
| It must currently be a real file object, not a |
| user-defined class emulating a file. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{load_dynamic}{name, pathname\optional{, file}} |
| Load and initialize a module implemented as a dynamically loadable |
| shared library and return its module object. If the module was |
| already initialized, it will be initialized \emph{again}. Some modules |
| don't like that and may raise an exception. The \var{pathname} |
| argument must point to the shared library. The \var{name} argument is |
| used to construct the name of the initialization function: an external |
| C function called \samp{init\var{name}()} in the shared library is |
| called. The optional \var{file} argument is ignored. (Note: using |
| shared libraries is highly system dependent, and not all systems |
| support it.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{load_source}{name, pathname, file} |
| Load and initialize a module implemented as a Python source file and |
| return its module object. If the module was already initialized, it |
| will be initialized \emph{again}. The \var{name} argument is used to |
| create or access a module object. The \var{pathname} argument points |
| to the source file. The \var{file} argument is the source |
| file, open for reading as text, from the beginning. |
| It must currently be a real file |
| object, not a user-defined class emulating a file. Note that if a |
| properly matching byte-compiled file (with suffix \file{.pyc} or |
| \file{.pyo}) exists, it will be used instead of parsing the given |
| source file. |
| \end{funcdesc} |
| |
| |
| \subsection{Examples} |
| \label{examples-imp} |
| |
| The following function emulates what was the standard import statement |
| up to Python 1.4 (i.e., no hierarchical module names). (This |
| \emph{implementation} wouldn't work in that version, since |
| \function{find_module()} has been extended and |
| \function{load_module()} has been added in 1.4.) |
| |
| \begin{verbatim} |
| import imp import sys |
| |
| def __import__(name, globals=None, locals=None, fromlist=None): |
| # Fast path: see if the module has already been imported. |
| try: |
| return sys.modules[name] |
| except KeyError: |
| 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: |
| return imp.load_module(name, fp, pathname, description) |
| finally: |
| # Since we may exit via an exception, close fp explicitly. |
| if fp: |
| fp.close() |
| \end{verbatim} |
| |
| A more complete example that implements hierarchical module names and |
| includes a \function{reload()}\bifuncindex{reload} function can be |
| found in the standard module \module{knee}\refstmodindex{knee} (which |
| is intended as an example only --- don't rely on any part of it being |
| a standard interface). |