Doc/lib/libpkgutil.tex

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