blob: 531c47445d6bbe107f4473be3fca608df379cff4 [file] [log] [blame]
Fred Drake295da241998-08-10 19:42:37 +00001\section{\module{imp} ---
Fred Drake4a406c61999-04-22 20:52:44 +00002 Access the \keyword{import} internals}
Fred Drakeb91e9341998-07-23 17:59:49 +00003
Fred Drake4a406c61999-04-22 20:52:44 +00004\declaremodule{builtin}{imp}
Fred Drakeb91e9341998-07-23 17:59:49 +00005\modulesynopsis{Access the implementation of the \keyword{import} statement.}
6
Guido van Rossum946805d1995-01-10 10:51:08 +00007
Fred Drake28b17701999-06-10 22:08:16 +00008This\stindex{import} module provides an interface to the mechanisms
Fred Drake4a406c61999-04-22 20:52:44 +00009used to implement the \keyword{import} statement. It defines the
10following constants and functions:
Guido van Rossum946805d1995-01-10 10:51:08 +000011
Guido van Rossum946805d1995-01-10 10:51:08 +000012
13\begin{funcdesc}{get_magic}{}
Fred Drake64c105d1998-08-11 15:18:45 +000014\indexii{file}{byte-code}
Guido van Rossum470be141995-03-17 16:07:09 +000015Return the magic string value used to recognize byte-compiled code
Fred Drake64c105d1998-08-11 15:18:45 +000016files (\file{.pyc} files). (This value may be different for each
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000017Python version.)
Guido van Rossum946805d1995-01-10 10:51:08 +000018\end{funcdesc}
19
20\begin{funcdesc}{get_suffixes}{}
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000021Return a list of triples, each describing a particular type of module.
Guido van Rossum946805d1995-01-10 10:51:08 +000022Each triple has the form \code{(\var{suffix}, \var{mode},
23\var{type})}, where \var{suffix} is a string to be appended to the
24module name to form the filename to search for, \var{mode} is the mode
Fred Drake64c105d1998-08-11 15:18:45 +000025string to pass to the built-in \function{open()} function to open the
26file (this can be \code{'r'} for text files or \code{'rb'} for binary
Guido van Rossum946805d1995-01-10 10:51:08 +000027files), and \var{type} is the file type, which has one of the values
Fred Drakebccc6401998-03-08 06:41:57 +000028\constant{PY_SOURCE}, \constant{PY_COMPILED}, or
29\constant{C_EXTENSION}, described below.
Guido van Rossum946805d1995-01-10 10:51:08 +000030\end{funcdesc}
31
Fred Drakec9a32ab1998-01-07 18:57:01 +000032\begin{funcdesc}{find_module}{name\optional{, path}}
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000033Try 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
Fred Drakebccc6401998-03-08 06:41:57 +000035for files with any of the suffixes returned by \function{get_suffixes()}
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000036above. Invalid names in the list are silently ignored (but all list
37items must be strings). If \var{path} is omitted or \code{None}, the
38list of directory names given by \code{sys.path} is searched, but
39first it searches a few special places: it tries to find a built-in
Fred Drakebccc6401998-03-08 06:41:57 +000040module with the given name (\constant{C_BUILTIN}), then a frozen module
41(\constant{PY_FROZEN}), and on some systems some other places are looked
42in as well (on the Mac, it looks for a resource (\constant{PY_RESOURCE});
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000043on Windows, it looks in the registry which may point to a specific
44file).
45
46If search is successful, the return value is a triple
Guido van Rossum946805d1995-01-10 10:51:08 +000047\code{(\var{file}, \var{pathname}, \var{description})} where
Guido van Rossum470be141995-03-17 16:07:09 +000048\var{file} is an open file object positioned at the beginning,
49\var{pathname} is the pathname of the
Guido van Rossum946805d1995-01-10 10:51:08 +000050file found, and \var{description} is a triple as contained in the list
Fred Drakebccc6401998-03-08 06:41:57 +000051returned by \function{get_suffixes()} describing the kind of module found.
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000052If 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
Thomas Woutersf8316632000-07-16 19:01:10 +000055mode; the module type is as indicate in parentheses above. If the
Fred Drakebccc6401998-03-08 06:41:57 +000056search is unsuccessful, \exception{ImportError} is raised. Other
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000057exceptions indicate problems with the arguments or environment.
58
59This function does not handle hierarchical module names (names
Fred Drake91f2f262001-07-06 19:28:48 +000060containing dots). In order to find \var{P}.\var{M}, that is, submodule
Fred Drakebccc6401998-03-08 06:41:57 +000061\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
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000064\code{\var{P}.__path__}. When \var{P} itself has a dotted name, apply
65this recipe recursively.
Guido van Rossum946805d1995-01-10 10:51:08 +000066\end{funcdesc}
67
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000068\begin{funcdesc}{load_module}{name, file, filename, description}
Fred Drakebccc6401998-03-08 06:41:57 +000069Load a module that was previously found by \function{find_module()} (or by
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000070an otherwise conducted search yielding compatible results). This
71function does more than importing the module: if the module was
Fred Drakebccc6401998-03-08 06:41:57 +000072already imported, it is equivalent to a
Fred Drake2c4f5542000-10-10 22:00:03 +000073\function{reload()}\bifuncindex{reload}! The \var{name} argument
74indicates the full module name (including the package name, if this is
75a submodule of a package). The \var{file} argument is an open file,
76and \var{filename} is the corresponding file name; these can be
77\code{None} and \code{''}, respectively, when the module is not being
78loaded from a file. The \var{description} argument is a tuple, as
79would be returned by \function{get_suffixes()}, describing what kind
80of module must be loaded.
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000081
82If the load is successful, the return value is the module object;
Fred Drakebccc6401998-03-08 06:41:57 +000083otherwise, an exception (usually \exception{ImportError}) is raised.
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000084
85\strong{Important:} the caller is responsible for closing the
86\var{file} argument, if it was not \code{None}, even when an exception
Fred Drakebccc6401998-03-08 06:41:57 +000087is raised. This is best done using a \keyword{try}
88... \keyword{finally} statement.
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000089\end{funcdesc}
90
91\begin{funcdesc}{new_module}{name}
92Return a new empty module object called \var{name}. This object is
Fred Drakec9a32ab1998-01-07 18:57:01 +000093\emph{not} inserted in \code{sys.modules}.
Guido van Rossum3cdb8f31997-09-09 20:53:37 +000094\end{funcdesc}
95
Tim Peters69232342001-08-30 05:16:13 +000096\begin{funcdesc}{lock_held}{}
Neal Norwitz6b353702002-04-09 18:15:00 +000097Return \code{True} if the import lock is currently held, else \code{False}.
98On platforms without threads, always return \code{False}.
Tim Peters69232342001-08-30 05:16:13 +000099
100On platforms with threads, a thread executing an import holds an internal
101lock until the import is complete.
102This lock blocks other threads from doing an import until the original
103import completes, which in turn prevents other threads from seeing
104incomplete module objects constructed by the original thread while in
105the process of completing its import (and the imports, if any,
106triggered by that).
107\end{funcdesc}
108
Just van Rossum3eb166b2002-11-29 20:47:40 +0000109\begin{funcdesc}{set_frozenmodules}{seq_of_tuples}
110Set the global list of frozen modules. \var{seq_of_tuples} is a sequence
111of tuples of length 3: (\var{modulename}, \var{codedata}, \var{ispkg})
112\var{modulename} is the name of the frozen module (may contain dots).
113\var{codedata} is a marshalled code object. \var{ispkg} is a boolean
114indicating whether the module is a package.
115\versionadded{2.3}
116\end{funcdesc}
117
118\begin{funcdesc}{get_frozenmodules}{}
119Return the global list of frozen modules as a tuple of tuples. See
120\function{set_frozenmodules()} for a description of its contents.
121\versionadded{2.3}
122\end{funcdesc}
123
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000124The following constants with integer values, defined in this module,
Fred Drakebccc6401998-03-08 06:41:57 +0000125are used to indicate the search result of \function{find_module()}.
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000126
127\begin{datadesc}{PY_SOURCE}
128The module was found as a source file.
129\end{datadesc}
130
131\begin{datadesc}{PY_COMPILED}
132The module was found as a compiled code object file.
133\end{datadesc}
134
135\begin{datadesc}{C_EXTENSION}
136The module was found as dynamically loadable shared library.
137\end{datadesc}
138
139\begin{datadesc}{PY_RESOURCE}
140The module was found as a Macintosh resource. This value can only be
141returned on a Macintosh.
142\end{datadesc}
143
144\begin{datadesc}{PKG_DIRECTORY}
145The module was found as a package directory.
146\end{datadesc}
147
148\begin{datadesc}{C_BUILTIN}
149The module was found as a built-in module.
150\end{datadesc}
151
152\begin{datadesc}{PY_FROZEN}
Fred Drakebccc6401998-03-08 06:41:57 +0000153The module was found as a frozen module (see \function{init_frozen()}).
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000154\end{datadesc}
155
156The following constant and functions are obsolete; their functionality
Fred Drakebccc6401998-03-08 06:41:57 +0000157is available through \function{find_module()} or \function{load_module()}.
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000158They are kept around for backward compatibility:
159
160\begin{datadesc}{SEARCH_ERROR}
161Unused.
162\end{datadesc}
163
Guido van Rossum946805d1995-01-10 10:51:08 +0000164\begin{funcdesc}{init_builtin}{name}
165Initialize the built-in module called \var{name} and return its module
166object. If the module was already initialized, it will be initialized
Fred Drakec9a32ab1998-01-07 18:57:01 +0000167\emph{again}. A few modules cannot be initialized twice --- attempting
Fred Drakebccc6401998-03-08 06:41:57 +0000168to initialize these again will raise an \exception{ImportError}
169exception. If there is no
Guido van Rossum946805d1995-01-10 10:51:08 +0000170built-in module called \var{name}, \code{None} is returned.
171\end{funcdesc}
172
173\begin{funcdesc}{init_frozen}{name}
174Initialize the frozen module called \var{name} and return its module
175object. If the module was already initialized, it will be initialized
Fred Drakec9a32ab1998-01-07 18:57:01 +0000176\emph{again}. If there is no frozen module called \var{name},
Guido van Rossum946805d1995-01-10 10:51:08 +0000177\code{None} is returned. (Frozen modules are modules written in
178Python whose compiled byte-code object is incorporated into a
Fred Drakebccc6401998-03-08 06:41:57 +0000179custom-built Python interpreter by Python's \program{freeze} utility.
180See \file{Tools/freeze/} for now.)
Guido van Rossum946805d1995-01-10 10:51:08 +0000181\end{funcdesc}
182
183\begin{funcdesc}{is_builtin}{name}
Fred Drakebccc6401998-03-08 06:41:57 +0000184Return \code{1} if there is a built-in module called \var{name} which
185can be initialized again. Return \code{-1} if there is a built-in
186module called \var{name} which cannot be initialized again (see
187\function{init_builtin()}). Return \code{0} if there is no built-in
188module called \var{name}.
Guido van Rossum946805d1995-01-10 10:51:08 +0000189\end{funcdesc}
190
191\begin{funcdesc}{is_frozen}{name}
Neal Norwitz6b353702002-04-09 18:15:00 +0000192Return \code{True} if there is a frozen module (see
193\function{init_frozen()}) called \var{name}, or \code{False} if there is
Fred Drakebccc6401998-03-08 06:41:57 +0000194no such module.
Guido van Rossum946805d1995-01-10 10:51:08 +0000195\end{funcdesc}
196
Fred Drakec9a32ab1998-01-07 18:57:01 +0000197\begin{funcdesc}{load_compiled}{name, pathname, file}
Fred Drake64c105d1998-08-11 15:18:45 +0000198\indexii{file}{byte-code}
Guido van Rossum946805d1995-01-10 10:51:08 +0000199Load and initialize a module implemented as a byte-compiled code file
200and return its module object. If the module was already initialized,
Fred Drakec9a32ab1998-01-07 18:57:01 +0000201it will be initialized \emph{again}. The \var{name} argument is used
Guido van Rossum946805d1995-01-10 10:51:08 +0000202to create or access a module object. The \var{pathname} argument
Guido van Rossum4d206541996-06-26 19:21:24 +0000203points to the byte-compiled code file. The \var{file}
Guido van Rossum946805d1995-01-10 10:51:08 +0000204argument is the byte-compiled code file, open for reading in binary
Guido van Rossum4d206541996-06-26 19:21:24 +0000205mode, from the beginning.
206It must currently be a real file object, not a
Guido van Rossum946805d1995-01-10 10:51:08 +0000207user-defined class emulating a file.
208\end{funcdesc}
209
Fred Drakec9a32ab1998-01-07 18:57:01 +0000210\begin{funcdesc}{load_dynamic}{name, pathname\optional{, file}}
Guido van Rossum946805d1995-01-10 10:51:08 +0000211Load and initialize a module implemented as a dynamically loadable
212shared library and return its module object. If the module was
Fred Drakec9a32ab1998-01-07 18:57:01 +0000213already initialized, it will be initialized \emph{again}. Some modules
Guido van Rossum946805d1995-01-10 10:51:08 +0000214don't like that and may raise an exception. The \var{pathname}
215argument must point to the shared library. The \var{name} argument is
216used to construct the name of the initialization function: an external
Fred Drakebccc6401998-03-08 06:41:57 +0000217C function called \samp{init\var{name}()} in the shared library is
Thomas Woutersf8316632000-07-16 19:01:10 +0000218called. The optional \var{file} argument is ignored. (Note: using
Guido van Rossum946805d1995-01-10 10:51:08 +0000219shared libraries is highly system dependent, and not all systems
220support it.)
221\end{funcdesc}
222
Fred Drakecce10901998-03-17 06:33:25 +0000223\begin{funcdesc}{load_source}{name, pathname, file}
Guido van Rossum946805d1995-01-10 10:51:08 +0000224Load and initialize a module implemented as a Python source file and
225return its module object. If the module was already initialized, it
Fred Drakec9a32ab1998-01-07 18:57:01 +0000226will be initialized \emph{again}. The \var{name} argument is used to
Guido van Rossum946805d1995-01-10 10:51:08 +0000227create or access a module object. The \var{pathname} argument points
Guido van Rossum4d206541996-06-26 19:21:24 +0000228to the source file. The \var{file} argument is the source
229file, open for reading as text, from the beginning.
230It must currently be a real file
Guido van Rossum946805d1995-01-10 10:51:08 +0000231object, not a user-defined class emulating a file. Note that if a
Fred Drake64c105d1998-08-11 15:18:45 +0000232properly matching byte-compiled file (with suffix \file{.pyc} or
233\file{.pyo}) exists, it will be used instead of parsing the given
234source file.
Guido van Rossum946805d1995-01-10 10:51:08 +0000235\end{funcdesc}
236
Fred Drakec83db331998-02-19 20:50:52 +0000237
Guido van Rossum946805d1995-01-10 10:51:08 +0000238\subsection{Examples}
Fred Drakec83db331998-02-19 20:50:52 +0000239\label{examples-imp}
240
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000241The following function emulates what was the standard import statement
Fred Drake91f2f262001-07-06 19:28:48 +0000242up to Python 1.4 (no hierarchical module names). (This
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000243\emph{implementation} wouldn't work in that version, since
Fred Drakebccc6401998-03-08 06:41:57 +0000244\function{find_module()} has been extended and
245\function{load_module()} has been added in 1.4.)
Guido van Rossum946805d1995-01-10 10:51:08 +0000246
Fred Drake19479911998-02-13 06:58:54 +0000247\begin{verbatim}
Fred Drake90badd12001-01-17 05:12:13 +0000248import imp
249import sys
Guido van Rossum946805d1995-01-10 10:51:08 +0000250
Guido van Rossum4f4c9b41995-02-15 15:52:13 +0000251def __import__(name, globals=None, locals=None, fromlist=None):
Guido van Rossum470be141995-03-17 16:07:09 +0000252 # Fast path: see if the module has already been imported.
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000253 try:
Guido van Rossum470be141995-03-17 16:07:09 +0000254 return sys.modules[name]
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000255 except KeyError:
256 pass
Guido van Rossum946805d1995-01-10 10:51:08 +0000257
Guido van Rossum470be141995-03-17 16:07:09 +0000258 # If any of the following calls raises an exception,
Guido van Rossum96628a91995-04-10 11:34:00 +0000259 # there's a problem we can't handle -- let the caller handle it.
Guido van Rossum470be141995-03-17 16:07:09 +0000260
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000261 fp, pathname, description = imp.find_module(name)
262
Guido van Rossumd6ac3801995-07-07 23:01:27 +0000263 try:
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000264 return imp.load_module(name, fp, pathname, description)
Guido van Rossumd6ac3801995-07-07 23:01:27 +0000265 finally:
266 # Since we may exit via an exception, close fp explicitly.
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000267 if fp:
268 fp.close()
Fred Drake19479911998-02-13 06:58:54 +0000269\end{verbatim}
Guido van Rossum3cdb8f31997-09-09 20:53:37 +0000270
271A more complete example that implements hierarchical module names and
Fred Drakebccc6401998-03-08 06:41:57 +0000272includes a \function{reload()}\bifuncindex{reload} function can be
Fred Drakebc82ab12002-04-08 05:22:30 +0000273found in the module \module{knee}\refmodindex{knee}. The
274\module{knee} module can be found in \file{Demo/imputil/} in the
275Python source distribution.