Doc/lib/libimp.tex

   1 \section{\module{imp} ---
   2          Access the \keyword{import} internals}
   3
   4 \declaremodule{builtin}{imp}
   5 \modulesynopsis{Access the implementation of the \keyword{import} statement.}
   6
   7
   8 This\stindex{import} module provides an interface to the mechanisms
   9 used to implement the \keyword{import} statement.  It defines the
  10 following constants and functions:
  11
  12
  13 \begin{funcdesc}{get_magic}{}
  14 \indexii{file}{byte-code}
  15 Return the magic string value used to recognize byte-compiled code
  16 files (\file{.pyc} files).  (This value may be different for each
  17 Python version.)
  18 \end{funcdesc}
  19
  20 \begin{funcdesc}{get_suffixes}{}
  21 Return a list of triples, each describing a particular type of module.
  22 Each triple has the form \code{(\var{suffix}, \var{mode},
  23 \var{type})}, where \var{suffix} is a string to be appended to the
  24 module name to form the filename to search for, \var{mode} is the mode
  25 string to pass to the built-in \function{open()} function to open the
  26 file (this can be \code{'r'} for text files or \code{'rb'} for binary
  27 files), and \var{type} is the file type, which has one of the values
  28 \constant{PY_SOURCE}, \constant{PY_COMPILED}, or
  29 \constant{C_EXTENSION}, described below.
  30 \end{funcdesc}
  31
  32 \begin{funcdesc}{find_module}{name\optional{, path}}
  33 Try to find the module \var{name} on the search path \var{path}.  If
  34 \var{path} is a list of directory names, each directory is searched
  35 for files with any of the suffixes returned by \function{get_suffixes()}
  36 above.  Invalid names in the list are silently ignored (but all list
  37 items must be strings).  If \var{path} is omitted or \code{None}, the
  38 list of directory names given by \code{sys.path} is searched, but
  39 first it searches a few special places: it tries to find a built-in
  40 module with the given name (\constant{C_BUILTIN}), then a frozen module
  41 (\constant{PY_FROZEN}), and on some systems some other places are looked
  42 in as well (on the Mac, it looks for a resource (\constant{PY_RESOURCE});
  43 on Windows, it looks in the registry which may point to a specific
  44 file).
  45
  46 If search is successful, the return value is a triple
  47 \code{(\var{file}, \var{pathname}, \var{description})} where
  48 \var{file} is an open file object positioned at the beginning,
  49 \var{pathname} is the pathname of the
  50 file found, and \var{description} is a triple as contained in the list
  51 returned by \function{get_suffixes()} describing the kind of module found.
  52 If the module does not live in a file, the returned \var{file} is
  53 \code{None}, \var{filename} is the empty string, and the
  54 \var{description} tuple contains empty strings for its suffix and
  55 mode; the module type is as indicate in parentheses above.  If the
  56 search is unsuccessful, \exception{ImportError} is raised.  Other
  57 exceptions indicate problems with the arguments or environment.
  58
  59 This function does not handle hierarchical module names (names
  60 containing dots).  In order to find \var{P}.\var{M}, that is, submodule
  61 \var{M} of package \var{P}, use \function{find_module()} and
  62 \function{load_module()} to find and load package \var{P}, and then use
  63 \function{find_module()} with the \var{path} argument set to
  64 \code{\var{P}.__path__}.  When \var{P} itself has a dotted name, apply
  65 this recipe recursively.
  66 \end{funcdesc}
  67
  68 \begin{funcdesc}{load_module}{name, file, filename, description}
  69 Load a module that was previously found by \function{find_module()} (or by
  70 an otherwise conducted search yielding compatible results).  This
  71 function does more than importing the module: if the module was
  72 already imported, it is equivalent to a
  73 \function{reload()}\bifuncindex{reload}!  The \var{name} argument
  74 indicates the full module name (including the package name, if this is
  75 a submodule of a package).  The \var{file} argument is an open file,
  76 and \var{filename} is the corresponding file name; these can be
  77 \code{None} and \code{''}, respectively, when the module is not being
  78 loaded from a file.  The \var{description} argument is a tuple, as
  79 would be returned by \function{get_suffixes()}, describing what kind
  80 of module must be loaded.
  81
  82 If the load is successful, the return value is the module object;
  83 otherwise, an exception (usually \exception{ImportError}) is raised.
  84
  85 \strong{Important:} the caller is responsible for closing the
  86 \var{file} argument, if it was not \code{None}, even when an exception
  87 is raised.  This is best done using a \keyword{try}
  88 ... \keyword{finally} statement.
  89 \end{funcdesc}
  90
  91 \begin{funcdesc}{new_module}{name}
  92 Return a new empty module object called \var{name}.  This object is
  93 \emph{not} inserted in \code{sys.modules}.
  94 \end{funcdesc}
  95
  96 \begin{funcdesc}{lock_held}{}
  97 Return \code{True} if the import lock is currently held, else \code{False}.
  98 On platforms without threads, always return \code{False}.
  99
 100 On platforms with threads, a thread executing an import holds an internal
 101 lock until the import is complete.
 102 This lock blocks other threads from doing an import until the original
 103 import completes, which in turn prevents other threads from seeing
 104 incomplete module objects constructed by the original thread while in
 105 the process of completing its import (and the imports, if any,
 106 triggered by that).
 107 \end{funcdesc}
 108
 109 The following constants with integer values, defined in this module,
 110 are used to indicate the search result of \function{find_module()}.
 111
 112 \begin{datadesc}{PY_SOURCE}
 113 The module was found as a source file.
 114 \end{datadesc}
 115
 116 \begin{datadesc}{PY_COMPILED}
 117 The module was found as a compiled code object file.
 118 \end{datadesc}
 119
 120 \begin{datadesc}{C_EXTENSION}
 121 The module was found as dynamically loadable shared library.
 122 \end{datadesc}
 123
 124 \begin{datadesc}{PY_RESOURCE}
 125 The module was found as a Macintosh resource.  This value can only be
 126 returned on a Macintosh.
 127 \end{datadesc}
 128
 129 \begin{datadesc}{PKG_DIRECTORY}
 130 The module was found as a package directory.
 131 \end{datadesc}
 132
 133 \begin{datadesc}{C_BUILTIN}
 134 The module was found as a built-in module.
 135 \end{datadesc}
 136
 137 \begin{datadesc}{PY_FROZEN}
 138 The module was found as a frozen module (see \function{init_frozen()}).
 139 \end{datadesc}
 140
 141 The following constant and functions are obsolete; their functionality
 142 is available through \function{find_module()} or \function{load_module()}.
 143 They are kept around for backward compatibility:
 144
 145 \begin{datadesc}{SEARCH_ERROR}
 146 Unused.
 147 \end{datadesc}
 148
 149 \begin{funcdesc}{init_builtin}{name}
 150 Initialize the built-in module called \var{name} and return its module
 151 object.  If the module was already initialized, it will be initialized
 152 \emph{again}.  A few modules cannot be initialized twice --- attempting
 153 to initialize these again will raise an \exception{ImportError}
 154 exception.  If there is no
 155 built-in module called \var{name}, \code{None} is returned.
 156 \end{funcdesc}
 157
 158 \begin{funcdesc}{init_frozen}{name}
 159 Initialize the frozen module called \var{name} and return its module
 160 object.  If the module was already initialized, it will be initialized
 161 \emph{again}.  If there is no frozen module called \var{name},
 162 \code{None} is returned.  (Frozen modules are modules written in
 163 Python whose compiled byte-code object is incorporated into a
 164 custom-built Python interpreter by Python's \program{freeze} utility.
 165 See \file{Tools/freeze/} for now.)
 166 \end{funcdesc}
 167
 168 \begin{funcdesc}{is_builtin}{name}
 169 Return \code{1} if there is a built-in module called \var{name} which
 170 can be initialized again.  Return \code{-1} if there is a built-in
 171 module called \var{name} which cannot be initialized again (see
 172 \function{init_builtin()}).  Return \code{0} if there is no built-in
 173 module called \var{name}.
 174 \end{funcdesc}
 175
 176 \begin{funcdesc}{is_frozen}{name}
 177 Return \code{True} if there is a frozen module (see
 178 \function{init_frozen()}) called \var{name}, or \code{False} if there is
 179 no such module.
 180 \end{funcdesc}
 181
 182 \begin{funcdesc}{load_compiled}{name, pathname, file}
 183 \indexii{file}{byte-code}
 184 Load and initialize a module implemented as a byte-compiled code file
 185 and return its module object.  If the module was already initialized,
 186 it will be initialized \emph{again}.  The \var{name} argument is used
 187 to create or access a module object.  The \var{pathname} argument
 188 points to the byte-compiled code file.  The \var{file}
 189 argument is the byte-compiled code file, open for reading in binary
 190 mode, from the beginning.
 191 It must currently be a real file object, not a
 192 user-defined class emulating a file.
 193 \end{funcdesc}
 194
 195 \begin{funcdesc}{load_dynamic}{name, pathname\optional{, file}}
 196 Load and initialize a module implemented as a dynamically loadable
 197 shared library and return its module object.  If the module was
 198 already initialized, it will be initialized \emph{again}.  Some modules
 199 don't like that and may raise an exception.  The \var{pathname}
 200 argument must point to the shared library.  The \var{name} argument is
 201 used to construct the name of the initialization function: an external
 202 C function called \samp{init\var{name}()} in the shared library is
 203 called.  The optional \var{file} argument is ignored.  (Note: using
 204 shared libraries is highly system dependent, and not all systems
 205 support it.)
 206 \end{funcdesc}
 207
 208 \begin{funcdesc}{load_source}{name, pathname, file}
 209 Load and initialize a module implemented as a Python source file and
 210 return its module object.  If the module was already initialized, it
 211 will be initialized \emph{again}.  The \var{name} argument is used to
 212 create or access a module object.  The \var{pathname} argument points
 213 to the source file.  The \var{file} argument is the source
 214 file, open for reading as text, from the beginning.
 215 It must currently be a real file
 216 object, not a user-defined class emulating a file.  Note that if a
 217 properly matching byte-compiled file (with suffix \file{.pyc} or
 218 \file{.pyo}) exists, it will be used instead of parsing the given
 219 source file.
 220 \end{funcdesc}
 221
 222
 223 \subsection{Examples}
 224 \label{examples-imp}
 225
 226 The following function emulates what was the standard import statement
 227 up to Python 1.4 (no hierarchical module names).  (This
 228 \emph{implementation} wouldn't work in that version, since
 229 \function{find_module()} has been extended and
 230 \function{load_module()} has been added in 1.4.)
 231
 232 \begin{verbatim}
 233 import imp
 234 import sys
 235
 236 def __import__(name, globals=None, locals=None, fromlist=None):
 237     # Fast path: see if the module has already been imported.
 238     try:
 239         return sys.modules[name]
 240     except KeyError:
 241         pass
 242
 243     # If any of the following calls raises an exception,
 244     # there's a problem we can't handle -- let the caller handle it.
 245
 246     fp, pathname, description = imp.find_module(name)
 247
 248     try:
 249         return imp.load_module(name, fp, pathname, description)
 250     finally:
 251         # Since we may exit via an exception, close fp explicitly.
 252         if fp:
 253             fp.close()
 254 \end{verbatim}
 255
 256 A more complete example that implements hierarchical module names and
 257 includes a \function{reload()}\bifuncindex{reload} function can be
 258 found in the module \module{knee}\refmodindex{knee}.  The
 259 \module{knee} module can be found in \file{Demo/imputil/} in the
 260 Python source distribution.