51 lines
2.0 KiB
TeX
51 lines
2.0 KiB
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}
|