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 \begin{funcdesc}{acquire_lock}{}
 110 Acquires the interpreter's import lock for the current thread.  This lock
 111 should be used by import hooks to ensure thread-safety when importing modules.
 112 On platforms without threads, this function does nothing.
 113 \versionadded{2.3}
 114 \end{funcdesc}
 115
 116 \begin{funcdesc}{release_lock}{}
 117 Release the interpreter's import lock.
 118 On platforms without threads, this function does nothing.
 119 \versionadded{2.3}
 120 \end{funcdesc}
 121
 122 The following constants with integer values, defined in this module,
 123 are used to indicate the search result of \function{find_module()}.
 124
 125 \begin{datadesc}{PY_SOURCE}
 126 The module was found as a source file.
 127 \end{datadesc}
 128
 129 \begin{datadesc}{PY_COMPILED}
 130 The module was found as a compiled code object file.
 131 \end{datadesc}
 132
 133 \begin{datadesc}{C_EXTENSION}
 134 The module was found as dynamically loadable shared library.
 135 \end{datadesc}
 136
 137 \begin{datadesc}{PY_RESOURCE}
 138 The module was found as a Macintosh resource.  This value can only be
 139 returned on a Macintosh.
 140 \end{datadesc}
 141
 142 \begin{datadesc}{PKG_DIRECTORY}
 143 The module was found as a package directory.
 144 \end{datadesc}
 145
 146 \begin{datadesc}{C_BUILTIN}
 147 The module was found as a built-in module.
 148 \end{datadesc}
 149
 150 \begin{datadesc}{PY_FROZEN}
 151 The module was found as a frozen module (see \function{init_frozen()}).
 152 \end{datadesc}
 153
 154 The following constant and functions are obsolete; their functionality
 155 is available through \function{find_module()} or \function{load_module()}.
 156 They are kept around for backward compatibility:
 157
 158 \begin{datadesc}{SEARCH_ERROR}
 159 Unused.
 160 \end{datadesc}
 161
 162 \begin{funcdesc}{init_builtin}{name}
 163 Initialize the built-in module called \var{name} and return its module
 164 object.  If the module was already initialized, it will be initialized
 165 \emph{again}.  A few modules cannot be initialized twice --- attempting
 166 to initialize these again will raise an \exception{ImportError}
 167 exception.  If there is no
 168 built-in module called \var{name}, \code{None} is returned.
 169 \end{funcdesc}
 170
 171 \begin{funcdesc}{init_frozen}{name}
 172 Initialize the frozen module called \var{name} and return its module
 173 object.  If the module was already initialized, it will be initialized
 174 \emph{again}.  If there is no frozen module called \var{name},
 175 \code{None} is returned.  (Frozen modules are modules written in
 176 Python whose compiled byte-code object is incorporated into a
 177 custom-built Python interpreter by Python's \program{freeze} utility.
 178 See \file{Tools/freeze/} for now.)
 179 \end{funcdesc}
 180
 181 \begin{funcdesc}{is_builtin}{name}
 182 Return \code{1} if there is a built-in module called \var{name} which
 183 can be initialized again.  Return \code{-1} if there is a built-in
 184 module called \var{name} which cannot be initialized again (see
 185 \function{init_builtin()}).  Return \code{0} if there is no built-in
 186 module called \var{name}.
 187 \end{funcdesc}
 188
 189 \begin{funcdesc}{is_frozen}{name}
 190 Return \code{True} if there is a frozen module (see
 191 \function{init_frozen()}) called \var{name}, or \code{False} if there is
 192 no such module.
 193 \end{funcdesc}
 194
 195 \begin{funcdesc}{load_compiled}{name, pathname, file}
 196 \indexii{file}{byte-code}
 197 Load and initialize a module implemented as a byte-compiled code file
 198 and return its module object.  If the module was already initialized,
 199 it will be initialized \emph{again}.  The \var{name} argument is used
 200 to create or access a module object.  The \var{pathname} argument
 201 points to the byte-compiled code file.  The \var{file}
 202 argument is the byte-compiled code file, open for reading in binary
 203 mode, from the beginning.
 204 It must currently be a real file object, not a
 205 user-defined class emulating a file.
 206 \end{funcdesc}
 207
 208 \begin{funcdesc}{load_dynamic}{name, pathname\optional{, file}}
 209 Load and initialize a module implemented as a dynamically loadable
 210 shared library and return its module object.  If the module was
 211 already initialized, it will be initialized \emph{again}.  Some modules
 212 don't like that and may raise an exception.  The \var{pathname}
 213 argument must point to the shared library.  The \var{name} argument is
 214 used to construct the name of the initialization function: an external
 215 C function called \samp{init\var{name}()} in the shared library is
 216 called.  The optional \var{file} argument is ignored.  (Note: using
 217 shared libraries is highly system dependent, and not all systems
 218 support it.)
 219 \end{funcdesc}
 220
 221 \begin{funcdesc}{load_source}{name, pathname, file}
 222 Load and initialize a module implemented as a Python source file and
 223 return its module object.  If the module was already initialized, it
 224 will be initialized \emph{again}.  The \var{name} argument is used to
 225 create or access a module object.  The \var{pathname} argument points
 226 to the source file.  The \var{file} argument is the source
 227 file, open for reading as text, from the beginning.
 228 It must currently be a real file
 229 object, not a user-defined class emulating a file.  Note that if a
 230 properly matching byte-compiled file (with suffix \file{.pyc} or
 231 \file{.pyo}) exists, it will be used instead of parsing the given
 232 source file.
 233 \end{funcdesc}
 234
 235
 236 \subsection{Examples}
 237 \label{examples-imp}
 238
 239 The following function emulates what was the standard import statement
 240 up to Python 1.4 (no hierarchical module names).  (This
 241 \emph{implementation} wouldn't work in that version, since
 242 \function{find_module()} has been extended and
 243 \function{load_module()} has been added in 1.4.)
 244
 245 \begin{verbatim}
 246 import imp
 247 import sys
 248
 249 def __import__(name, globals=None, locals=None, fromlist=None):
 250     # Fast path: see if the module has already been imported.
 251     try:
 252         return sys.modules[name]
 253     except KeyError:
 254         pass
 255
 256     # If any of the following calls raises an exception,
 257     # there's a problem we can't handle -- let the caller handle it.
 258
 259     fp, pathname, description = imp.find_module(name)
 260
 261     try:
 262         return imp.load_module(name, fp, pathname, description)
 263     finally:
 264         # Since we may exit via an exception, close fp explicitly.
 265         if fp:
 266             fp.close()
 267 \end{verbatim}
 268
 269 A more complete example that implements hierarchical module names and
 270 includes a \function{reload()}\bifuncindex{reload} function can be
 271 found in the module \module{knee}\refmodindex{knee}.  The
 272 \module{knee} module can be found in \file{Demo/imputil/} in the
 273 Python source distribution.