add hg and python

1 files changed, 291 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libimp.tex b/sys/src/cmd/python/Doc/lib/libimp.tex
new file mode 100644
index 000000000..598d35182
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libimp.tex
@@ -0,0 +1,291 @@
+\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.  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 \exception{ImportError}
+exception.  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}.  Some modules
+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 \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.