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