\section{\module{pkgutil} --- Package extension utility}\declaremodule{standard}{pkgutil}\modulesynopsis{Utilities to support extension of packages.}\versionadded{2.3}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 on 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}
\section{\module{pkgutil} ---
Package extension utility}
\declaremodule{standard}{pkgutil}
\modulesynopsis{Utilities to support extension of packages.}
\versionadded{2.3}
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 on 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}