PageRenderTime 244ms CodeModel.GetById 100ms app.highlight 3ms RepoModel.GetById 138ms app.codeStats 0ms

ReStructuredText | 64 lines | 44 code | 20 blank | 0 comment | 0 complexity | e32f2517766fa700f70a4bddee89ed5a MD5 | raw file
 2:mod:`pkgutil` --- Package extension utility
 5.. module:: pkgutil
 6   :synopsis: Utilities to support extension of packages.
 9.. versionadded:: 2.3
11This module provides functions to manipulate packages:
14.. function:: extend_path(path, name)
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:``::
19      from pkgutil import extend_path
20      __path__ = extend_path(__path__, __name__)
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.
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.)
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.
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).
44.. function:: get_data(package, resource)
46   Get a resource from a package.
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   ( 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 ``/``).
54   The function returns a binary string that is the contents of the
55   specified resource.
57   For packages located in the filesystem, which have already been imported,
58   this is the rough equivalent of::
60       d = os.path.dirname(sys.modules[package].__file__)
61       data = open(os.path.join(d, resource), 'rb').read()
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.