blob: 317c903033cc22c84aa901a964f30665c4031e76 [file] [log] [blame]
Guido van Rossum470be141995-03-17 16:07:09 +00001\section{Built-in Module \sectcode{imp}}
Guido van Rossume47da0a1997-07-17 16:34:52 +00002\label{module-imp}
Guido van Rossum946805d1995-01-10 10:51:08 +00003\bimodindex{imp}
4\index{import}
5
Guido van Rossum6c4f0031995-03-07 10:14:09 +00006This module provides an interface to the mechanisms used to implement
Guido van Rossum946805d1995-01-10 10:51:08 +00007the \code{import} statement. It defines the following constants and
8functions:
9
Fred Drake19479911998-02-13 06:58:54 +000010\setindexsubitem{(in module imp)}
Guido van Rossum946805d1995-01-10 10:51:08 +000011
12\begin{funcdesc}{get_magic}{}
Guido van Rossum470be141995-03-17 16:07:09 +000013Return the magic string value used to recognize byte-compiled code
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000014files (``\code{.pyc} files''). (This value may be different for each
15Python version.)
Guido van Rossum946805d1995-01-10 10:51:08 +000016\end{funcdesc}
17
18\begin{funcdesc}{get_suffixes}{}
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000019Return a list of triples, each describing a particular type of module.
Guido van Rossum946805d1995-01-10 10:51:08 +000020Each triple has the form \code{(\var{suffix}, \var{mode},
21\var{type})}, where \var{suffix} is a string to be appended to the
22module name to form the filename to search for, \var{mode} is the mode
23string 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
25files), and \var{type} is the file type, which has one of the values
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000026\code{PY_SOURCE}, \code{PY_COMPILED}, or \code{C_EXTENSION}, defined
27below.
Guido van Rossum946805d1995-01-10 10:51:08 +000028\end{funcdesc}
29
Fred Drakec9a32ab1998-01-07 18:57:01 +000030\begin{funcdesc}{find_module}{name\optional{, path}}
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000031Try 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
33for files with any of the suffixes returned by \code{get_suffixes()}
34above. Invalid names in the list are silently ignored (but all list
35items must be strings). If \var{path} is omitted or \code{None}, the
36list of directory names given by \code{sys.path} is searched, but
37first it searches a few special places: it tries to find a built-in
38module with the given name (\code{C_BUILTIN}), then a frozen module
39(\code{PY_FROZEN}), and on some systems some other places are looked
40in as well (on the Mac, it looks for a resource (\code{PY_RESOURCE});
41on Windows, it looks in the registry which may point to a specific
42file).
43
44If search is successful, the return value is a triple
Guido van Rossum946805d1995-01-10 10:51:08 +000045\code{(\var{file}, \var{pathname}, \var{description})} where
Guido van Rossum470be141995-03-17 16:07:09 +000046\var{file} is an open file object positioned at the beginning,
47\var{pathname} is the pathname of the
Guido van Rossum946805d1995-01-10 10:51:08 +000048file found, and \var{description} is a triple as contained in the list
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000049returned by \code{get_suffixes} describing the kind of module found.
50If 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
53mode; the module type is as indicate in parentheses dabove. If the
54search is unsuccessful, \code{ImportError} is raised. Other
55exceptions indicate problems with the arguments or environment.
56
57This function does not handle hierarchical module names (names
Fred Drakecc974541997-12-29 17:16:24 +000058containing dots). In order to find \var{P}.\var{M}, i.e., submodule
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000059\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
63this recipe recursively.
Guido van Rossum946805d1995-01-10 10:51:08 +000064\end{funcdesc}
65
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000066\begin{funcdesc}{load_module}{name, file, filename, description}
67Load a module that was previously found by \code{find_module()} (or by
68an otherwise conducted search yielding compatible results). This
69function does more than importing the module: if the module was
70already imported, it is equivalent to a \code{reload()}! The
71\var{name} argument indicates the full module name (including the
72package name, if this is a submodule of a package). The \var{file}
73argument is an open file, and \var{filename} is the corresponding
74file name; these can be \code{None} and \code{""}, respectively, when
75the module is not being loaded from a file. The \var{description}
76argument is a tuple as returned by \code{find_module()} describing what
77kind of module must be loaded.
78
79If the load is successful, the return value is the module object;
80otherwise, 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
84is raised. This is best done using a try-finally statement.
85\end{funcdesc}
86
87\begin{funcdesc}{new_module}{name}
88Return a new empty module object called \var{name}. This object is
Fred Drakec9a32ab1998-01-07 18:57:01 +000089\emph{not} inserted in \code{sys.modules}.
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000090\end{funcdesc}
91
92The following constants with integer values, defined in this module,
93are used to indicate the search result of \code{find_module()}.
94
95\begin{datadesc}{PY_SOURCE}
96The module was found as a source file.
97\end{datadesc}
98
99\begin{datadesc}{PY_COMPILED}
100The module was found as a compiled code object file.
101\end{datadesc}
102
103\begin{datadesc}{C_EXTENSION}
104The module was found as dynamically loadable shared library.
105\end{datadesc}
106
107\begin{datadesc}{PY_RESOURCE}
108The module was found as a Macintosh resource. This value can only be
109returned on a Macintosh.
110\end{datadesc}
111
112\begin{datadesc}{PKG_DIRECTORY}
113The module was found as a package directory.
114\end{datadesc}
115
116\begin{datadesc}{C_BUILTIN}
117The module was found as a built-in module.
118\end{datadesc}
119
120\begin{datadesc}{PY_FROZEN}
Fred Drakec9a32ab1998-01-07 18:57:01 +0000121The module was found as a frozen module (see \code{init_frozen()}).
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000122\end{datadesc}
123
124The following constant and functions are obsolete; their functionality
125is available through \code{find_module()} or \code{load_module()}.
126They are kept around for backward compatibility:
127
128\begin{datadesc}{SEARCH_ERROR}
129Unused.
130\end{datadesc}
131
Guido van Rossum946805d1995-01-10 10:51:08 +0000132\begin{funcdesc}{init_builtin}{name}
133Initialize the built-in module called \var{name} and return its module
134object. If the module was already initialized, it will be initialized
Fred Drakec9a32ab1998-01-07 18:57:01 +0000135\emph{again}. A few modules cannot be initialized twice --- attempting
Guido van Rossum6bb1adc1995-03-13 10:03:32 +0000136to initialize these again will raise an \code{ImportError} exception.
137If there is no
Guido van Rossum946805d1995-01-10 10:51:08 +0000138built-in module called \var{name}, \code{None} is returned.
139\end{funcdesc}
140
141\begin{funcdesc}{init_frozen}{name}
142Initialize the frozen module called \var{name} and return its module
143object. If the module was already initialized, it will be initialized
Fred Drakec9a32ab1998-01-07 18:57:01 +0000144\emph{again}. If there is no frozen module called \var{name},
Guido van Rossum946805d1995-01-10 10:51:08 +0000145\code{None} is returned. (Frozen modules are modules written in
146Python whose compiled byte-code object is incorporated into a
147custom-built Python interpreter by Python's \code{freeze} utility.
Fred Drakec9a32ab1998-01-07 18:57:01 +0000148See \file{Tools/freeze} for now.)
Guido van Rossum946805d1995-01-10 10:51:08 +0000149\end{funcdesc}
150
151\begin{funcdesc}{is_builtin}{name}
152Return \code{1} if there is a built-in module called \var{name} which can be
153initialized again. Return \code{-1} if there is a built-in module
154called \var{name} which cannot be initialized again (see
Fred Drakec9a32ab1998-01-07 18:57:01 +0000155\code{init_builtin()}). Return \code{0} if there is no built-in module
Guido van Rossum946805d1995-01-10 10:51:08 +0000156called \var{name}.
157\end{funcdesc}
158
159\begin{funcdesc}{is_frozen}{name}
Fred Drakec9a32ab1998-01-07 18:57:01 +0000160Return \code{1} if there is a frozen module (see \code{init_frozen()})
Guido van Rossum946805d1995-01-10 10:51:08 +0000161called \var{name}, \code{0} if there is no such module.
162\end{funcdesc}
163
Fred Drakec9a32ab1998-01-07 18:57:01 +0000164\begin{funcdesc}{load_compiled}{name, pathname, file}
Guido van Rossum946805d1995-01-10 10:51:08 +0000165Load and initialize a module implemented as a byte-compiled code file
166and return its module object. If the module was already initialized,
Fred Drakec9a32ab1998-01-07 18:57:01 +0000167it will be initialized \emph{again}. The \var{name} argument is used
Guido van Rossum946805d1995-01-10 10:51:08 +0000168to create or access a module object. The \var{pathname} argument
Guido van Rossum4d206541996-06-26 19:21:24 +0000169points to the byte-compiled code file. The \var{file}
Guido van Rossum946805d1995-01-10 10:51:08 +0000170argument is the byte-compiled code file, open for reading in binary
Guido van Rossum4d206541996-06-26 19:21:24 +0000171mode, from the beginning.
172It must currently be a real file object, not a
Guido van Rossum946805d1995-01-10 10:51:08 +0000173user-defined class emulating a file.
174\end{funcdesc}
175
Fred Drakec9a32ab1998-01-07 18:57:01 +0000176\begin{funcdesc}{load_dynamic}{name, pathname\optional{, file}}
Guido van Rossum946805d1995-01-10 10:51:08 +0000177Load and initialize a module implemented as a dynamically loadable
178shared library and return its module object. If the module was
Fred Drakec9a32ab1998-01-07 18:57:01 +0000179already initialized, it will be initialized \emph{again}. Some modules
Guido van Rossum946805d1995-01-10 10:51:08 +0000180don't like that and may raise an exception. The \var{pathname}
181argument must point to the shared library. The \var{name} argument is
182used to construct the name of the initialization function: an external
183C function called \code{init\var{name}()} in the shared library is
184called. The optional \var{file} argment is ignored. (Note: using
185shared libraries is highly system dependent, and not all systems
186support it.)
187\end{funcdesc}
188
Guido van Rossum4d206541996-06-26 19:21:24 +0000189\begin{funcdesc}{load_source}{name\, pathname\, file}
Guido van Rossum946805d1995-01-10 10:51:08 +0000190Load and initialize a module implemented as a Python source file and
191return its module object. If the module was already initialized, it
Fred Drakec9a32ab1998-01-07 18:57:01 +0000192will be initialized \emph{again}. The \var{name} argument is used to
Guido van Rossum946805d1995-01-10 10:51:08 +0000193create or access a module object. The \var{pathname} argument points
Guido van Rossum4d206541996-06-26 19:21:24 +0000194to the source file. The \var{file} argument is the source
195file, open for reading as text, from the beginning.
196It must currently be a real file
Guido van Rossum946805d1995-01-10 10:51:08 +0000197object, not a user-defined class emulating a file. Note that if a
198properly matching byte-compiled file (with suffix \code{.pyc}) exists,
199it will be used instead of parsing the given source file.
200\end{funcdesc}
201
Fred Drakec83db331998-02-19 20:50:52 +0000202
Guido van Rossum946805d1995-01-10 10:51:08 +0000203\subsection{Examples}
Fred Drakec83db331998-02-19 20:50:52 +0000204\label{examples-imp}
205
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000206The following function emulates what was the standard import statement
207up to Python 1.4 (i.e., no hierarchical module names). (This
208\emph{implementation} wouldn't work in that version, since
209\code{imp.find_module()} has been extended and
210\code{imp.load_module()} has been added in 1.4.)
Guido van Rossum946805d1995-01-10 10:51:08 +0000211
Fred Drake19479911998-02-13 06:58:54 +0000212\begin{verbatim}
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000213import imp import sys
Guido van Rossum946805d1995-01-10 10:51:08 +0000214
Guido van Rossum4f4c9b41995-02-15 15:52:13 +0000215def __import__(name, globals=None, locals=None, fromlist=None):
Guido van Rossum470be141995-03-17 16:07:09 +0000216 # Fast path: see if the module has already been imported.
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000217 try:
Guido van Rossum470be141995-03-17 16:07:09 +0000218 return sys.modules[name]
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000219 except KeyError:
220 pass
Guido van Rossum946805d1995-01-10 10:51:08 +0000221
Guido van Rossum470be141995-03-17 16:07:09 +0000222 # If any of the following calls raises an exception,
Guido van Rossum96628a91995-04-10 11:34:00 +0000223 # there's a problem we can't handle -- let the caller handle it.
Guido van Rossum470be141995-03-17 16:07:09 +0000224
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000225 fp, pathname, description = imp.find_module(name)
226
Guido van Rossumd6ac3801995-07-07 23:01:27 +0000227 try:
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000228 return imp.load_module(name, fp, pathname, description)
Guido van Rossumd6ac3801995-07-07 23:01:27 +0000229 finally:
230 # Since we may exit via an exception, close fp explicitly.
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000231 if fp:
232 fp.close()
Fred Drake19479911998-02-13 06:58:54 +0000233\end{verbatim}
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000234
235A more complete example that implements hierarchical module names and
236includes a \code{reload()} function can be found in the standard
Fred Drakec9a32ab1998-01-07 18:57:01 +0000237module \code{knee}\refstmodindex{knee} (which is intended as an
238example only -- don't rely on any part of it being a standard
239interface).