[Python-checkins] python/dist/src/Doc/lib libpkgutil.tex,NONE,1.1 lib.tex,1.206,1.207

[fdrake@users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv30700/lib

Modified Files:
	lib.tex 
Added Files:
	libpkgutil.tex 
Log Message:
Added docs for (draft) pkgutil module.

--- NEW FILE: libpkgutil.tex ---
\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}

Index: lib.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/lib.tex,v
retrieving revision 1.206
retrieving revision 1.207
diff -C2 -d -r1.206 -r1.207
*** lib.tex	14 Nov 2002 03:58:20 -0000	1.206
--- lib.tex	23 Dec 2002 16:53:59 -0000	1.207
***************
*** 91,94 ****
--- 91,95 ----
  \input{libwarnings}
  \input{libimp}
+ \input{libpkgutil}
  \input{libcode}
  \input{libcodeop}