\index{import}
This module provides an interface to the mechanisms used to implement
-the \code{import} statement. It defines the following constants and
+the \keyword{import} statement. It defines the following constants and
functions:
-\setindexsubitem{(in module imp)}
\begin{funcdesc}{get_magic}{}
Return the magic string value used to recognize byte-compiled code
string to pass to the built-in \code{open} function to open the file
(this can be \code{'r'} for text files or \code{'rb'} for binary
files), and \var{type} is the file type, which has one of the values
-\code{PY_SOURCE}, \code{PY_COMPILED}, or \code{C_EXTENSION}, defined
-below.
+\constant{PY_SOURCE}, \constant{PY_COMPILED}, or
+\constant{C_EXTENSION}, described below.
\end{funcdesc}
\begin{funcdesc}{find_module}{name\optional{, path}}
Try to find the module \var{name} on the search path \var{path}. If
\var{path} is a list of directory names, each directory is searched
-for files with any of the suffixes returned by \code{get_suffixes()}
+for files with any of the suffixes returned by \function{get_suffixes()}
above. Invalid names in the list are silently ignored (but all list
items must be strings). If \var{path} is omitted or \code{None}, the
list of directory names given by \code{sys.path} is searched, but
first it searches a few special places: it tries to find a built-in
-module with the given name (\code{C_BUILTIN}), then a frozen module
-(\code{PY_FROZEN}), and on some systems some other places are looked
-in as well (on the Mac, it looks for a resource (\code{PY_RESOURCE});
+module with the given name (\constant{C_BUILTIN}), then a frozen module
+(\constant{PY_FROZEN}), and on some systems some other places are looked
+in as well (on the Mac, it looks for a resource (\constant{PY_RESOURCE});
on Windows, it looks in the registry which may point to a specific
file).
\var{file} is an open file object positioned at the beginning,
\var{pathname} is the pathname of the
file found, and \var{description} is a triple as contained in the list
-returned by \code{get_suffixes} describing the kind of module found.
+returned by \function{get_suffixes()} describing the kind of module found.
If the module does not live in a file, the returned \var{file} is
\code{None}, \var{filename} is the empty string, and the
\var{description} tuple contains empty strings for its suffix and
mode; the module type is as indicate in parentheses dabove. If the
-search is unsuccessful, \code{ImportError} is raised. Other
+search is unsuccessful, \exception{ImportError} is raised. Other
exceptions indicate problems with the arguments or environment.
This function does not handle hierarchical module names (names
containing dots). In order to find \var{P}.\var{M}, i.e., submodule
-\var{M} of package \var{P}, use \code{find_module()} and
-\code{load_module()} to find and load package \var{P}, and then use
-\code{find_module()} with the \var{path} argument set to
+\var{M} of package \var{P}, use \function{find_module()} and
+\function{load_module()} to find and load package \var{P}, and then use
+\function{find_module()} with the \var{path} argument set to
\code{\var{P}.__path__}. When \var{P} itself has a dotted name, apply
this recipe recursively.
\end{funcdesc}
\begin{funcdesc}{load_module}{name, file, filename, description}
-Load a module that was previously found by \code{find_module()} (or by
+Load a module that was previously found by \function{find_module()} (or by
an otherwise conducted search yielding compatible results). This
function does more than importing the module: if the module was
-already imported, it is equivalent to a \code{reload()}! The
+already imported, it is equivalent to a
+\function{reload()}\bifuncindex{reload}! The
\var{name} argument indicates the full module name (including the
package name, if this is a submodule of a package). The \var{file}
argument is an open file, and \var{filename} is the corresponding
-file name; these can be \code{None} and \code{""}, respectively, when
+file name; these can be \code{None} and \code{''}, respectively, when
the module is not being loaded from a file. The \var{description}
-argument is a tuple as returned by \code{find_module()} describing what
-kind of module must be loaded.
+argument is a tuple as returned by \function{find_module()} describing
+what kind of module must be loaded.
If the load is successful, the return value is the module object;
-otherwise, an exception (usually \code{ImportError}) is raised.
+otherwise, an exception (usually \exception{ImportError}) is raised.
\strong{Important:} the caller is responsible for closing the
\var{file} argument, if it was not \code{None}, even when an exception
-is raised. This is best done using a try-finally statement.
+is raised. This is best done using a \keyword{try}
+... \keyword{finally} statement.
\end{funcdesc}
\begin{funcdesc}{new_module}{name}
\end{funcdesc}
The following constants with integer values, defined in this module,
-are used to indicate the search result of \code{find_module()}.
+are used to indicate the search result of \function{find_module()}.
\begin{datadesc}{PY_SOURCE}
The module was found as a source file.
\end{datadesc}
\begin{datadesc}{PY_FROZEN}
-The module was found as a frozen module (see \code{init_frozen()}).
+The module was found as a frozen module (see \function{init_frozen()}).
\end{datadesc}
The following constant and functions are obsolete; their functionality
-is available through \code{find_module()} or \code{load_module()}.
+is available through \function{find_module()} or \function{load_module()}.
They are kept around for backward compatibility:
\begin{datadesc}{SEARCH_ERROR}
Initialize the built-in module called \var{name} and return its module
object. If the module was already initialized, it will be initialized
\emph{again}. A few modules cannot be initialized twice --- attempting
-to initialize these again will raise an \code{ImportError} exception.
-If there is no
+to initialize these again will raise an \exception{ImportError}
+exception. If there is no
built-in module called \var{name}, \code{None} is returned.
\end{funcdesc}
\emph{again}. If there is no frozen module called \var{name},
\code{None} is returned. (Frozen modules are modules written in
Python whose compiled byte-code object is incorporated into a
-custom-built Python interpreter by Python's \code{freeze} utility.
-See \file{Tools/freeze} for now.)
+custom-built Python interpreter by Python's \program{freeze} utility.
+See \file{Tools/freeze/} for now.)
\end{funcdesc}
\begin{funcdesc}{is_builtin}{name}
-Return \code{1} if there is a built-in module called \var{name} which can be
-initialized again. Return \code{-1} if there is a built-in module
-called \var{name} which cannot be initialized again (see
-\code{init_builtin()}). Return \code{0} if there is no built-in module
-called \var{name}.
+Return \code{1} if there is a built-in module called \var{name} which
+can be initialized again. Return \code{-1} if there is a built-in
+module called \var{name} which cannot be initialized again (see
+\function{init_builtin()}). Return \code{0} if there is no built-in
+module called \var{name}.
\end{funcdesc}
\begin{funcdesc}{is_frozen}{name}
-Return \code{1} if there is a frozen module (see \code{init_frozen()})
-called \var{name}, \code{0} if there is no such module.
+Return \code{1} if there is a frozen module (see
+\function{init_frozen()}) called \var{name}, or \code{0} if there is
+no such module.
\end{funcdesc}
\begin{funcdesc}{load_compiled}{name, pathname, file}
don't like that and may raise an exception. The \var{pathname}
argument must point to the shared library. The \var{name} argument is
used to construct the name of the initialization function: an external
-C function called \code{init\var{name}()} in the shared library is
+C function called \samp{init\var{name}()} in the shared library is
called. The optional \var{file} argment is ignored. (Note: using
shared libraries is highly system dependent, and not all systems
support it.)
file, open for reading as text, from the beginning.
It must currently be a real file
object, not a user-defined class emulating a file. Note that if a
-properly matching byte-compiled file (with suffix \code{.pyc}) exists,
+properly matching byte-compiled file (with suffix \file{.pyc}) exists,
it will be used instead of parsing the given source file.
\end{funcdesc}
The following function emulates what was the standard import statement
up to Python 1.4 (i.e., no hierarchical module names). (This
\emph{implementation} wouldn't work in that version, since
-\code{imp.find_module()} has been extended and
-\code{imp.load_module()} has been added in 1.4.)
+\function{find_module()} has been extended and
+\function{load_module()} has been added in 1.4.)
\begin{verbatim}
import imp import sys
\end{verbatim}
A more complete example that implements hierarchical module names and
-includes a \code{reload()} function can be found in the standard
-module \code{knee}\refstmodindex{knee} (which is intended as an
-example only -- don't rely on any part of it being a standard
-interface).
+includes a \function{reload()}\bifuncindex{reload} function can be
+found in the standard module \module{knee}\refstmodindex{knee} (which
+is intended as an example only --- don't rely on any part of it being
+a standard interface).
\index{import}
This module provides an interface to the mechanisms used to implement
-the \code{import} statement. It defines the following constants and
+the \keyword{import} statement. It defines the following constants and
functions:
-\setindexsubitem{(in module imp)}
\begin{funcdesc}{get_magic}{}
Return the magic string value used to recognize byte-compiled code
string to pass to the built-in \code{open} function to open the file
(this can be \code{'r'} for text files or \code{'rb'} for binary
files), and \var{type} is the file type, which has one of the values
-\code{PY_SOURCE}, \code{PY_COMPILED}, or \code{C_EXTENSION}, defined
-below.
+\constant{PY_SOURCE}, \constant{PY_COMPILED}, or
+\constant{C_EXTENSION}, described below.
\end{funcdesc}
\begin{funcdesc}{find_module}{name\optional{, path}}
Try to find the module \var{name} on the search path \var{path}. If
\var{path} is a list of directory names, each directory is searched
-for files with any of the suffixes returned by \code{get_suffixes()}
+for files with any of the suffixes returned by \function{get_suffixes()}
above. Invalid names in the list are silently ignored (but all list
items must be strings). If \var{path} is omitted or \code{None}, the
list of directory names given by \code{sys.path} is searched, but
first it searches a few special places: it tries to find a built-in
-module with the given name (\code{C_BUILTIN}), then a frozen module
-(\code{PY_FROZEN}), and on some systems some other places are looked
-in as well (on the Mac, it looks for a resource (\code{PY_RESOURCE});
+module with the given name (\constant{C_BUILTIN}), then a frozen module
+(\constant{PY_FROZEN}), and on some systems some other places are looked
+in as well (on the Mac, it looks for a resource (\constant{PY_RESOURCE});
on Windows, it looks in the registry which may point to a specific
file).
\var{file} is an open file object positioned at the beginning,
\var{pathname} is the pathname of the
file found, and \var{description} is a triple as contained in the list
-returned by \code{get_suffixes} describing the kind of module found.
+returned by \function{get_suffixes()} describing the kind of module found.
If the module does not live in a file, the returned \var{file} is
\code{None}, \var{filename} is the empty string, and the
\var{description} tuple contains empty strings for its suffix and
mode; the module type is as indicate in parentheses dabove. If the
-search is unsuccessful, \code{ImportError} is raised. Other
+search is unsuccessful, \exception{ImportError} is raised. Other
exceptions indicate problems with the arguments or environment.
This function does not handle hierarchical module names (names
containing dots). In order to find \var{P}.\var{M}, i.e., submodule
-\var{M} of package \var{P}, use \code{find_module()} and
-\code{load_module()} to find and load package \var{P}, and then use
-\code{find_module()} with the \var{path} argument set to
+\var{M} of package \var{P}, use \function{find_module()} and
+\function{load_module()} to find and load package \var{P}, and then use
+\function{find_module()} with the \var{path} argument set to
\code{\var{P}.__path__}. When \var{P} itself has a dotted name, apply
this recipe recursively.
\end{funcdesc}
\begin{funcdesc}{load_module}{name, file, filename, description}
-Load a module that was previously found by \code{find_module()} (or by
+Load a module that was previously found by \function{find_module()} (or by
an otherwise conducted search yielding compatible results). This
function does more than importing the module: if the module was
-already imported, it is equivalent to a \code{reload()}! The
+already imported, it is equivalent to a
+\function{reload()}\bifuncindex{reload}! The
\var{name} argument indicates the full module name (including the
package name, if this is a submodule of a package). The \var{file}
argument is an open file, and \var{filename} is the corresponding
-file name; these can be \code{None} and \code{""}, respectively, when
+file name; these can be \code{None} and \code{''}, respectively, when
the module is not being loaded from a file. The \var{description}
-argument is a tuple as returned by \code{find_module()} describing what
-kind of module must be loaded.
+argument is a tuple as returned by \function{find_module()} describing
+what kind of module must be loaded.
If the load is successful, the return value is the module object;
-otherwise, an exception (usually \code{ImportError}) is raised.
+otherwise, an exception (usually \exception{ImportError}) is raised.
\strong{Important:} the caller is responsible for closing the
\var{file} argument, if it was not \code{None}, even when an exception
-is raised. This is best done using a try-finally statement.
+is raised. This is best done using a \keyword{try}
+... \keyword{finally} statement.
\end{funcdesc}
\begin{funcdesc}{new_module}{name}
\end{funcdesc}
The following constants with integer values, defined in this module,
-are used to indicate the search result of \code{find_module()}.
+are used to indicate the search result of \function{find_module()}.
\begin{datadesc}{PY_SOURCE}
The module was found as a source file.
\end{datadesc}
\begin{datadesc}{PY_FROZEN}
-The module was found as a frozen module (see \code{init_frozen()}).
+The module was found as a frozen module (see \function{init_frozen()}).
\end{datadesc}
The following constant and functions are obsolete; their functionality
-is available through \code{find_module()} or \code{load_module()}.
+is available through \function{find_module()} or \function{load_module()}.
They are kept around for backward compatibility:
\begin{datadesc}{SEARCH_ERROR}
Initialize the built-in module called \var{name} and return its module
object. If the module was already initialized, it will be initialized
\emph{again}. A few modules cannot be initialized twice --- attempting
-to initialize these again will raise an \code{ImportError} exception.
-If there is no
+to initialize these again will raise an \exception{ImportError}
+exception. If there is no
built-in module called \var{name}, \code{None} is returned.
\end{funcdesc}
\emph{again}. If there is no frozen module called \var{name},
\code{None} is returned. (Frozen modules are modules written in
Python whose compiled byte-code object is incorporated into a
-custom-built Python interpreter by Python's \code{freeze} utility.
-See \file{Tools/freeze} for now.)
+custom-built Python interpreter by Python's \program{freeze} utility.
+See \file{Tools/freeze/} for now.)
\end{funcdesc}
\begin{funcdesc}{is_builtin}{name}
-Return \code{1} if there is a built-in module called \var{name} which can be
-initialized again. Return \code{-1} if there is a built-in module
-called \var{name} which cannot be initialized again (see
-\code{init_builtin()}). Return \code{0} if there is no built-in module
-called \var{name}.
+Return \code{1} if there is a built-in module called \var{name} which
+can be initialized again. Return \code{-1} if there is a built-in
+module called \var{name} which cannot be initialized again (see
+\function{init_builtin()}). Return \code{0} if there is no built-in
+module called \var{name}.
\end{funcdesc}
\begin{funcdesc}{is_frozen}{name}
-Return \code{1} if there is a frozen module (see \code{init_frozen()})
-called \var{name}, \code{0} if there is no such module.
+Return \code{1} if there is a frozen module (see
+\function{init_frozen()}) called \var{name}, or \code{0} if there is
+no such module.
\end{funcdesc}
\begin{funcdesc}{load_compiled}{name, pathname, file}
don't like that and may raise an exception. The \var{pathname}
argument must point to the shared library. The \var{name} argument is
used to construct the name of the initialization function: an external
-C function called \code{init\var{name}()} in the shared library is
+C function called \samp{init\var{name}()} in the shared library is
called. The optional \var{file} argment is ignored. (Note: using
shared libraries is highly system dependent, and not all systems
support it.)
file, open for reading as text, from the beginning.
It must currently be a real file
object, not a user-defined class emulating a file. Note that if a
-properly matching byte-compiled file (with suffix \code{.pyc}) exists,
+properly matching byte-compiled file (with suffix \file{.pyc}) exists,
it will be used instead of parsing the given source file.
\end{funcdesc}
The following function emulates what was the standard import statement
up to Python 1.4 (i.e., no hierarchical module names). (This
\emph{implementation} wouldn't work in that version, since
-\code{imp.find_module()} has been extended and
-\code{imp.load_module()} has been added in 1.4.)
+\function{find_module()} has been extended and
+\function{load_module()} has been added in 1.4.)
\begin{verbatim}
import imp import sys
\end{verbatim}
A more complete example that implements hierarchical module names and
-includes a \code{reload()} function can be found in the standard
-module \code{knee}\refstmodindex{knee} (which is intended as an
-example only -- don't rely on any part of it being a standard
-interface).
+includes a \function{reload()}\bifuncindex{reload} function can be
+found in the standard module \module{knee}\refstmodindex{knee} (which
+is intended as an example only --- don't rely on any part of it being
+a standard interface).
projects / python / commitdiff