diff --git a/Doc/Makefile.deps b/Doc/Makefile.deps index f1673c14b2b..f3845b845a7 100644 --- a/Doc/Makefile.deps +++ b/Doc/Makefile.deps @@ -120,6 +120,7 @@ LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \ lib/libmarshal.tex \ lib/libwarnings.tex \ lib/libimp.tex \ + lib/libpkgutil.tex \ lib/libparser.tex \ lib/libbltin.tex \ lib/libmain.tex \ diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 35112634c7e..9f6f5266dc4 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -90,6 +90,7 @@ and how to embed it in other applications. \input{libmarshal} \input{libwarnings} \input{libimp} +\input{libpkgutil} \input{libcode} \input{libcodeop} \input{libpprint} diff --git a/Doc/lib/libpkgutil.tex b/Doc/lib/libpkgutil.tex new file mode 100644 index 00000000000..b45f7eb46a4 --- /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}