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