Doc/libimp.tex

   1 \section{Built-in module \sectcode{imp}}
   2 \bimodindex{imp}
   3 \index{import}
   4
   5 This module provides an interface to the mechanisms use to implement
   6 the \code{import} statement.  It defines the following constants and
   7 functions:
   8
   9 \renewcommand{\indexsubitem}{(in module struct)}
  10
  11 \begin{funcdesc}{get_magic}{}
  12 Return the magic string used to recognize value byte-compiled code
  13 files (``\code{.pyc} files'').
  14 \end{funcdesc}
  15
  16 \begin{funcdesc}{get_suffixes}{}
  17 Return a list of triples, each describing a particular type of file.
  18 Each triple has the form \code{(\var{suffix}, \var{mode},
  19 \var{type})}, where \var{suffix} is a string to be appended to the
  20 module name to form the filename to search for, \var{mode} is the mode
  21 string to pass to the built-in \code{open} function to open the file
  22 (this can be \code{'r'} for text files or \code{'rb'} for binary
  23 files), and \var{type} is the file type, which has one of the values
  24 \code{PY_SOURCE}, \code{PY_COMPILED} or \code{C_EXTENSION}, defined
  25 below.
  26 \end{funcdesc}
  27
  28 \begin{funcdesc}{find_module}{name\, \optional{path}}
  29 Try to find the module \var{name} on the search path \var{path}.  The
  30 default \var{path} is \code{sys.path}.  The return value is a triple
  31 \code{(\var{file}, \var{pathname}, \var{description})} where
  32 \var{file} is an open file object positioned at the beginning
  33 corresponding to the file found, \var{pathname} is the pathname of the
  34 file found, and \var{description} is a triple as contained in the list
  35 returned by \code{get_suffixes} describing the kind of file found.
  36 \end{funcdesc}
  37
  38 \begin{funcdesc}{init_builtin}{name}
  39 Initialize the built-in module called \var{name} and return its module
  40 object.  If the module was already initialized, it will be initialized
  41 {\em again}.  A few modules cannot be initialized twice -- attempting
  42 to initialize these again will raise an exception.  If there is no
  43 built-in module called \var{name}, \code{None} is returned.
  44 \end{funcdesc}
  45
  46 \begin{funcdesc}{init_frozen}{name}
  47 Initialize the frozen module called \var{name} and return its module
  48 object.  If the module was already initialized, it will be initialized
  49 {\em again}.  If there is no frozen module called \var{name},
  50 \code{None} is returned.  (Frozen modules are modules written in
  51 Python whose compiled byte-code object is incorporated into a
  52 custom-built Python interpreter by Python's \code{freeze} utility.
  53 See \code{Demo/freeze} for now.)
  54 \end{funcdesc}
  55
  56 \begin{funcdesc}{is_builtin}{name}
  57 Return \code{1} if there is a built-in module called \var{name} which can be
  58 initialized again.  Return \code{-1} if there is a built-in module
  59 called \var{name} which cannot be initialized again (see
  60 \code{init_builtin}).  Return \code{0} if there is no built-in module
  61 called \var{name}.
  62 \end{funcdesc}
  63
  64 \begin{funcdesc}{is_frozen}{name}
  65 Return \code{1} if there is a frozen module (see \code{init_frozen})
  66 called \var{name}, \code{0} if there is no such module.
  67 \end{funcdesc}
  68
  69 \begin{funcdesc}{load_compiled}{name\, pathname\, \optional{file}}
  70 Load and initialize a module implemented as a byte-compiled code file
  71 and return its module object.  If the module was already initialized,
  72 it will be initialized {\em again}.  The \var{name} argument is used
  73 to create or access a module object.  The \var{pathname} argument
  74 points to the byte-compiled code file.  The optional \var{file}
  75 argument is the byte-compiled code file, open for reading in binary
  76 mode, from the beginning -- if not given, the function opens
  77 \var{pathname}.  It must currently be a real file object, not a
  78 user-defined class emulating a file.
  79 \end{funcdesc}
  80
  81 \begin{funcdesc}{load_dynamic}{name\, pathname\, \optional{file}}
  82 Load and initialize a module implemented as a dynamically loadable
  83 shared library and return its module object.  If the module was
  84 already initialized, it will be initialized {\em again}.  Some modules
  85 don't like that and may raise an exception.  The \var{pathname}
  86 argument must point to the shared library.  The \var{name} argument is
  87 used to construct the name of the initialization function: an external
  88 C function called \code{init\var{name}()} in the shared library is
  89 called.  The optional \var{file} argment is ignored.  (Note: using
  90 shared libraries is highly system dependent, and not all systems
  91 support it.)
  92 \end{funcdesc}
  93
  94 \begin{funcdesc}{load_source}{name\, pathname\, \optional{file}}
  95 Load and initialize a module implemented as a Python source file and
  96 return its module object.  If the module was already initialized, it
  97 will be initialized {\em again}.  The \var{name} argument is used to
  98 create or access a module object.  The \var{pathname} argument points
  99 to the source file.  The optional \var{file} argument is the source
 100 file, open for reading as text, from the beginning -- if not given,
 101 the function opens \var{pathname}.  It must currently be a real file
 102 object, not a user-defined class emulating a file.  Note that if a
 103 properly matching byte-compiled file (with suffix \code{.pyc}) exists,
 104 it will be used instead of parsing the given source file.
 105 \end{funcdesc}
 106
 107 \begin{funcdesc}{new_module}{name}
 108 Return a new empty module object called \var{name}.  This object is
 109 {\em not} inserted in \code{sys.modules}.
 110 \end{funcdesc}
 111
 112 The following constants with integer values, defined in the module,
 113 are used to indicate the search result of \code{imp.find_module}.
 114
 115 \begin{datadesc}{SEARCH_ERROR}
 116 The module was not found.
 117 \end{datadesc}
 118
 119 \begin{datadesc}{PY_SOURCE}
 120 The module was found as a source file.
 121 \end{datadesc}
 122
 123 \begin{datadesc}{PY_COMPILED}
 124 The module was found as a compiled code object file.
 125 \end{datadesc}
 126
 127 \begin{datadesc}{C_EXTENSION}
 128 The module was found as dynamically loadable shared library.
 129 \end{datadesc}
 130
 131 \subsection{Examples}
 132 The following function emulates the default import statement:
 133
 134 \begin{verbatim}
 135 import imp
 136 from sys import modules
 137
 138 def __import__(name):
 139     # Fast path: let's see if it's already in sys.modules.
 140     # Two speed optimizations are worth mentioning:
 141     # - We use 'modules' instead of 'sys.modules'; this saves a
 142     #   dictionary look-up per call.
 143     # - It's also faster to use a try-except statement than
 144     #   to use modules.has_key(name) to check if it's there.
 145     try:
 146         return modules[name]
 147     except KeyError:
 148         pass
 149
 150     # See if it's a built-in module
 151     m = imp.init_builtin(name)
 152     if m:
 153         return m
 154
 155     # See if it's a frozen module
 156     m = imp.init_frozen(name)
 157     if m:
 158         return m
 159
 160     # Search the default path (i.e. sys.path).
 161     # If this raises an exception, the module is not found --
 162     # let the caller handle the exception.
 163     fp, pathname, (suffix, mode, type) = imp.find_module(name)
 164
 165     # See what we got.
 166     # Note that fp will be closed automatically when we return.
 167     if type == imp.C_EXTENSION:
 168         return imp.load_dynamic(name, pathname)
 169     if type == imp.PY_SOURCE:
 170         return imp.load_source(name, pathname, fp)
 171     if type == imp.PY_COMPILED:
 172         return imp.load_source(name, pathname, fp)
 173
 174     # Shouldn't get here at all.
 175     raise ImportError, '%s: unknown module type (%d)' % (name, type)
 176 \end{verbatim}