261 lines
11 KiB
TeX
261 lines
11 KiB
TeX
\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}, that is, 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
|
|
would be returned by \function{get_suffixes()}, 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}
|
|
|
|
\begin{funcdesc}{lock_held}{}
|
|
Return \code{True} if the import lock is currently held, else \code{False}.
|
|
On platforms without threads, always return \code{False}.
|
|
|
|
On platforms with threads, a thread executing an import holds an internal
|
|
lock until the import is complete.
|
|
This lock blocks other threads from doing an import until the original
|
|
import completes, which in turn prevents other threads from seeing
|
|
incomplete module objects constructed by the original thread while in
|
|
the process of completing its import (and the imports, if any,
|
|
triggered by that).
|
|
\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{True} if there is a frozen module (see
|
|
\function{init_frozen()}) called \var{name}, or \code{False} 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 (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 module \module{knee}\refmodindex{knee}. The
|
|
\module{knee} module can be found in \file{Demo/imputil/} in the
|
|
Python source distribution.
|