Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | |
| 2 | :mod:`pkgutil` --- Package extension utility |
| 3 | ============================================ |
| 4 | |
| 5 | .. module:: pkgutil |
| 6 | :synopsis: Utilities to support extension of packages. |
| 7 | |
| 8 | |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 9 | This module provides functions to manipulate packages: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
| 11 | |
| 12 | .. function:: extend_path(path, name) |
| 13 | |
| 14 | Extend the search path for the modules which comprise a package. Intended use is |
| 15 | to place the following code in a package's :file:`__init__.py`:: |
| 16 | |
| 17 | from pkgutil import extend_path |
| 18 | __path__ = extend_path(__path__, __name__) |
| 19 | |
| 20 | This will add to the package's ``__path__`` all subdirectories of directories on |
| 21 | ``sys.path`` named after the package. This is useful if one wants to distribute |
| 22 | different parts of a single logical package as multiple directories. |
| 23 | |
| 24 | It also looks for :file:`\*.pkg` files beginning where ``*`` matches the *name* |
| 25 | argument. This feature is similar to :file:`\*.pth` files (see the :mod:`site` |
| 26 | module for more information), except that it doesn't special-case lines starting |
| 27 | with ``import``. A :file:`\*.pkg` file is trusted at face value: apart from |
| 28 | checking for duplicates, all entries found in a :file:`\*.pkg` file are added to |
| 29 | the path, regardless of whether they exist on the filesystem. (This is a |
| 30 | feature.) |
| 31 | |
| 32 | If the input path is not a list (as is the case for frozen packages) it is |
| 33 | returned unchanged. The input path is not modified; an extended copy is |
| 34 | returned. Items are only appended to the copy at the end. |
| 35 | |
| 36 | It is assumed that ``sys.path`` is a sequence. Items of ``sys.path`` that are |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 37 | not strings referring to existing directories are ignored. Unicode items on |
| 38 | ``sys.path`` that cause errors when used as filenames may cause this function |
| 39 | to raise an exception (in line with :func:`os.path.isdir` behavior). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 40 | |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 41 | .. function:: get_data(package, resource) |
| 42 | |
| 43 | Get a resource from a package. |
| 44 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 45 | This is a wrapper for the PEP 302 loader :func:`get_data` API. The package |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 46 | argument should be the name of a package, in standard module format |
| 47 | (foo.bar). The resource argument should be in the form of a relative |
| 48 | filename, using ``/`` as the path separator. The parent directory name |
| 49 | ``..`` is not allowed, and nor is a rooted name (starting with a ``/``). |
| 50 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 51 | The function returns a binary string that is the contents of the |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 52 | specified resource. |
| 53 | |
| 54 | For packages located in the filesystem, which have already been imported, |
| 55 | this is the rough equivalent of:: |
| 56 | |
| 57 | d = os.path.dirname(sys.modules[package].__file__) |
| 58 | data = open(os.path.join(d, resource), 'rb').read() |
| 59 | |
| 60 | If the package cannot be located or loaded, or it uses a PEP 302 loader |
| 61 | which does not support :func:`get_data`, then None is returned. |