diff options
Diffstat (limited to 'Doc/lib/libimp.tex')
| -rw-r--r-- | Doc/lib/libimp.tex | 292 |
1 files changed, 0 insertions, 292 deletions
diff --git a/Doc/lib/libimp.tex b/Doc/lib/libimp.tex deleted file mode 100644 index 5379309..0000000 --- a/Doc/lib/libimp.tex +++ /dev/null @@ -1,292 +0,0 @@ -\section{\module{imp} --- - Access the \keyword{import} internals} - -\declaremodule{builtin}{imp} -\modulesynopsis{Access the implementation of the \keyword{import} statement.} - - -This\stindex{import} module provides an interface to the mechanisms -used to implement the \keyword{import} statement. It defines the -following constants and functions: - - -\begin{funcdesc}{get_magic}{} -\indexii{file}{byte-code} -Return the magic string value used to recognize byte-compiled code -files (\file{.pyc} files). (This value may be different for each -Python version.) -\end{funcdesc} - -\begin{funcdesc}{get_suffixes}{} -Return a list of triples, each describing a particular type of module. -Each triple has the form \code{(\var{suffix}, \var{mode}, -\var{type})}, where \var{suffix} is a string to be appended to the -module name to form the filename to search for, \var{mode} is the mode -string to pass to the built-in \function{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 -\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 \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 (\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). - -If search is successful, the return value is a triple -\code{(\var{file}, \var{pathname}, \var{description})} where -\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 \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 above. If the -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}, that is, submodule -\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 \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 -\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 the module is not being -loaded from a file. The \var{description} argument is a tuple, as -would be returned by \function{get_suffixes()}, describing what kind -of module must be loaded. - -If the load is successful, the return value is the module object; -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 \keyword{try} -... \keyword{finally} statement. -\end{funcdesc} - -\begin{funcdesc}{new_module}{name} -Return a new empty module object called \var{name}. This object is -\emph{not} inserted in \code{sys.modules}. -\end{funcdesc} - -\begin{funcdesc}{lock_held}{} -Return \code{True} if the import lock is currently held, else \code{False}. -On platforms without threads, always return \code{False}. - -On platforms with threads, a thread executing an import holds an internal -lock until the import is complete. -This lock blocks other threads from doing an import until the original -import completes, which in turn prevents other threads from seeing -incomplete module objects constructed by the original thread while in -the process of completing its import (and the imports, if any, -triggered by that). -\end{funcdesc} - -\begin{funcdesc}{acquire_lock}{} -Acquires the interpreter's import lock for the current thread. This lock -should be used by import hooks to ensure thread-safety when importing modules. -On platforms without threads, this function does nothing. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{release_lock}{} -Release the interpreter's import lock. -On platforms without threads, this function does nothing. -\versionadded{2.3} -\end{funcdesc} - -The following constants with integer values, defined in this 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_COMPILED} -The module was found as a compiled code object file. -\end{datadesc} - -\begin{datadesc}{C_EXTENSION} -The module was found as dynamically loadable shared library. -\end{datadesc} - -\begin{datadesc}{PY_RESOURCE} -The module was found as a Mac OS 9 resource. This value can only be -returned on a Mac OS 9 or earlier Macintosh. -\end{datadesc} - -\begin{datadesc}{PKG_DIRECTORY} -The module was found as a package directory. -\end{datadesc} - -\begin{datadesc}{C_BUILTIN} -The module was found as a built-in module. -\end{datadesc} - -\begin{datadesc}{PY_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 \function{find_module()} or \function{load_module()}. -They are kept around for backward compatibility: - -\begin{datadesc}{SEARCH_ERROR} -Unused. -\end{datadesc} - -\begin{funcdesc}{init_builtin}{name} -Initialize the built-in module called \var{name} and return its module -object along with storing it in \code{sys.modules}. If the module was already -initialized, it will be initialized \emph{again}. Re-initialization involves -the copying of the built-in module's \code{__dict__} from the cached -module over the module's entry in \code{sys.modules}. If there is no -built-in module called \var{name}, \code{None} is returned. -\end{funcdesc} - -\begin{funcdesc}{init_frozen}{name} -Initialize the frozen module called \var{name} and return its module -object. If the module was already initialized, it will be initialized -\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 \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 -\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{True} if there is a frozen module (see -\function{init_frozen()}) called \var{name}, or \code{False} if there is -no such module. -\end{funcdesc} - -\begin{funcdesc}{load_compiled}{name, pathname, \optional{file}} -\indexii{file}{byte-code} -Load and initialize a module implemented as a byte-compiled code file -and return its module object. If the module was already initialized, -it will be initialized \emph{again}. The \var{name} argument is used -to create or access a module object. The \var{pathname} argument -points to the byte-compiled code file. The \var{file} -argument is the byte-compiled code file, open for reading in binary -mode, from the beginning. -It must currently be a real file object, not a -user-defined class emulating a file. -\end{funcdesc} - -\begin{funcdesc}{load_dynamic}{name, pathname\optional{, file}} -Load and initialize a module implemented as a dynamically loadable -shared library and return its module object. If the module was -already initialized, it will be initialized \emph{again}. -Re-initialization involves copying the \code{__dict__} attribute of the cached -instance of the module over the value used in the module cached in -\code{sys.modules}. 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 -\samp{init\var{name}()} in the shared library is called. The optional -\var{file} argument is ignored. (Note: using shared libraries is highly -system dependent, and not all systems support it.) -\end{funcdesc} - -\begin{funcdesc}{load_source}{name, pathname\optional{, file}} -Load and initialize a module implemented as a Python source file and -return its module object. If the module was already initialized, it -will be initialized \emph{again}. The \var{name} argument is used to -create or access a module object. The \var{pathname} argument points -to the source file. The \var{file} argument is the source -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 \file{.pyc} or -\file{.pyo}) exists, it will be used instead of parsing the given -source file. -\end{funcdesc} - -\begin{classdesc}{NullImporter}{path_string} -The \class{NullImporter} type is a \pep{302} import hook that handles -non-directory path strings by failing to find any modules. Calling this -type with an existing directory or empty string raises -\exception{ImportError}. Otherwise, a \class{NullImporter} instance is -returned. - -Python adds instances of this type to \code{sys.path_importer_cache} for -any path entries that are not directories and are not handled by any other -path hooks on \code{sys.path_hooks}. Instances have only one method: - -\begin{methoddesc}{find_module}{fullname \optional{, path}} -This method always returns \code{None}, indicating that the requested -module could not be found. -\end{methoddesc} - -\versionadded{2.5} -\end{classdesc} - -\subsection{Examples} -\label{examples-imp} - -The following function emulates what was the standard import statement -up to Python 1.4 (no hierarchical module names). (This -\emph{implementation} wouldn't work in that version, since -\function{find_module()} has been extended and -\function{load_module()} has been added in 1.4.) - -\begin{verbatim} -import imp -import sys - -def __import__(name, globals=None, locals=None, fromlist=None): - # Fast path: see if the module has already been imported. - try: - return sys.modules[name] - except KeyError: - pass - - # If any of the following calls raises an exception, - # there's a problem we can't handle -- let the caller handle it. - - fp, pathname, description = imp.find_module(name) - - try: - return imp.load_module(name, fp, pathname, description) - finally: - # Since we may exit via an exception, close fp explicitly. - if fp: - fp.close() -\end{verbatim} - -A more complete example that implements hierarchical module names and -includes a \function{reload()}\bifuncindex{reload} function can be -found in the module \module{knee}\refmodindex{knee}. The -\module{knee} module can be found in \file{Demo/imputil/} in the -Python source distribution. |