|
| 1 | +\section{\module{pkgutil} --- |
| 2 | + Package extension utility} |
| 3 | + |
| 4 | +\declaremodule{standard}{pkgutil} |
| 5 | +\modulesynopsis{Utilities to support extension of packages.} |
| 6 | + |
| 7 | +\versionadded{2.3} |
| 8 | + |
| 9 | +\begin{notice}[warning] |
| 10 | + This is an experimental module. It may be withdrawn or completely |
| 11 | + changed up to an including the release of Python 2.3 beta 1. |
| 12 | +\end{notice} |
| 13 | + |
| 14 | +This module provides a single function: |
| 15 | + |
| 16 | +\begin{funcdesc}{extend_path}{path, name} |
| 17 | + Extend the search path for the modules which comprise a package. |
| 18 | + Intended use is to place the following code in a package's |
| 19 | + \file{__init__.py}: |
| 20 | + |
| 21 | +\begin{verbatim} |
| 22 | +from pkgutil import extend_path |
| 23 | +__path__ = extend_path(__path__, __name__) |
| 24 | +\end{verbatim} |
| 25 | + |
| 26 | + This will add to the package's \code{__path__} all subdirectories of |
| 27 | + directories on \code{sys.path} named after the package. This is |
| 28 | + useful if one wants to distribute different parts of a single |
| 29 | + logical package as multiple directories. |
| 30 | + |
| 31 | + It also looks for \file{*.pkg} files beginning where \code{*} |
| 32 | + matches the \var{name} argument. This feature is similar to |
| 33 | + \file{*.pth} files (see the \refmodule{site} module for more |
| 34 | + information), except that it doesn't special-case lines starting |
| 35 | + with \code{import}. A \file{*.pkg} file is trusted at face value: |
| 36 | + apart from checking for duplicates, all entries found in a |
| 37 | + \file{*.pkg} file are added to the path, regardless of whether they |
| 38 | + exist the filesystem. (This is a feature.) |
| 39 | + |
| 40 | + If the input path is not a list (as is the case for frozen |
| 41 | + packages) it is returned unchanged. The input path is not |
| 42 | + modified; an extended copy is returned. Items are only appended |
| 43 | + to the copy at the end. |
| 44 | + |
| 45 | + It is assumed that \code{sys.path} is a sequence. Items of |
| 46 | + \code{sys.path} that are not (Unicode or 8-bit) strings referring to |
| 47 | + existing directories are ignored. Unicode items on \code{sys.path} |
| 48 | + that cause errors when used as filenames may cause this function to |
| 49 | + raise an exception (in line with \function{os.path.isdir()} behavior). |
| 50 | +\end{funcdesc} |
0 commit comments