Added docs for (draft) pkgutil module.

1 files changed, 50 insertions, 0 deletions

diff --git a/Doc/lib/libpkgutil.tex b/Doc/lib/libpkgutil.tex
new file mode 100644
index 0000000..b45f7eb
--- /dev/null
+++ b/Doc/lib/libpkgutil.tex
@@ -0,0 +1,50 @@
+\section{\module{pkgutil} ---
+         Package extension utility}
+
+\declaremodule{standard}{pkgutil}
+\modulesynopsis{Utilities to support extension of packages.}
+
+\versionadded{2.3}
+
+\begin{notice}[warning]
+  This is an experimental module.  It may be withdrawn or completely
+  changed up to an including the release of Python 2.3 beta 1.
+\end{notice}
+
+This module provides a single function:
+
+\begin{funcdesc}{extend_path}{path, name}
+  Extend the search path for the modules which comprise a package.
+  Intended use is to place the following code in a package's
+  \file{__init__.py}:
+
+\begin{verbatim}
+from pkgutil import extend_path
+__path__ = extend_path(__path__, __name__)
+\end{verbatim}
+
+  This will add to the package's \code{__path__} all subdirectories of
+  directories on \code{sys.path} named after the package.  This is
+  useful if one wants to distribute different parts of a single
+  logical package as multiple directories.
+
+  It also looks for \file{*.pkg} files beginning where \code{*}
+  matches the \var{name} argument.  This feature is similar to
+  \file{*.pth} files (see the \refmodule{site} module for more
+  information), except that it doesn't special-case lines starting
+  with \code{import}.  A \file{*.pkg} file is trusted at face value:
+  apart from checking for duplicates, all entries found in a
+  \file{*.pkg} file are added to the path, regardless of whether they
+  exist the filesystem.  (This is a feature.)
+
+  If the input path is not a list (as is the case for frozen
+  packages) it is returned unchanged.  The input path is not
+  modified; an extended copy is returned.  Items are only appended
+  to the copy at the end.
+
+  It is assumed that \code{sys.path} is a sequence.  Items of
+  \code{sys.path} that are not (Unicode or 8-bit) strings referring to
+  existing directories are ignored.  Unicode items on \code{sys.path}
+  that cause errors when used as filenames may cause this function to
+  raise an exception (in line with \function{os.path.isdir()} behavior).
+\end{funcdesc}