1 

     2 :mod:`pkgutil` --- Package extension utility

     3 ============================================

     4 

     5 .. module:: pkgutil

     6    :synopsis: Utilities to support extension of packages.

     7 

     8 

     9 .. versionadded:: 2.3

    10 

    11 This module provides functions to manipulate packages:

    12 

    13 

    14 .. function:: extend_path(path, name)

    15 

    16    Extend the search path for the modules which comprise a package. Intended use is

    17    to place the following code in a package's :file:`__init__.py`::

    18 

    19       from pkgutil import extend_path

    20       __path__ = extend_path(__path__, __name__)

    21 

    22    This will add to the package's ``__path__`` all subdirectories of directories on

    23    ``sys.path`` named after the package.  This is useful if one wants to distribute

    24    different parts of a single logical package as multiple directories.

    25 

    26    It also looks for :file:`\*.pkg` files beginning where ``*`` matches the *name*

    27    argument.  This feature is similar to :file:`\*.pth` files (see the :mod:`site`

    28    module for more information), except that it doesn't special-case lines starting

    29    with ``import``.  A :file:`\*.pkg` file is trusted at face value: apart from

    30    checking for duplicates, all entries found in a :file:`\*.pkg` file are added to

    31    the path, regardless of whether they exist on the filesystem.  (This is a

    32    feature.)

    33 

    34    If the input path is not a list (as is the case for frozen packages) it is

    35    returned unchanged.  The input path is not modified; an extended copy is

    36    returned.  Items are only appended to the copy at the end.

    37 

    38    It is assumed that ``sys.path`` is a sequence.  Items of ``sys.path`` that are

    39    not (Unicode or 8-bit) strings referring to existing directories are ignored.

    40    Unicode items on ``sys.path`` that cause errors when used as filenames may cause

    41    this function to raise an exception (in line with :func:`os.path.isdir`

    42    behavior).

    43 

    44 .. function:: get_data(package, resource)

    45 

    46    Get a resource from a package.

    47 

    48    This is a wrapper for the PEP 302 loader :func:`get_data` API. The package

    49    argument should be the name of a package, in standard module format

    50    (foo.bar). The resource argument should be in the form of a relative

    51    filename, using ``/`` as the path separator. The parent directory name

    52    ``..`` is not allowed, and nor is a rooted name (starting with a ``/``).

    53 

    54    The function returns a binary string that is the contents of the

    55    specified resource.

    56 

    57    For packages located in the filesystem, which have already been imported,

    58    this is the rough equivalent of::

    59 

    60        d = os.path.dirname(sys.modules[package].__file__)

    61        data = open(os.path.join(d, resource), 'rb').read()

    62 

    63    If the package cannot be located or loaded, or it uses a PEP 302 loader

    64    which does not support :func:`get_data`, then None is returned.