### Navigation

- index
- modules |
- next |
- previous |
- Python v3.1a1 documentation »
- The Python Standard Library »
- Importing Modules »

# `pkgutil` — Package extension utility

This module provides functions to manipulate packages:

`pkgutil.``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 `__init__.py`:

      from pkgutil import extend_path
      __path__ = extend_path(__path__, __name__)

  This will add to the package’s `__path__` all subdirectories of directories on `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 `*.pkg` files beginning where `*` matches the name argument. This feature is similar to `*.pth` files (see the `site` module for more information), except that it doesn’t special-case lines starting with `import`. A `*.pkg` file is trusted at face value: apart from checking for duplicates, all entries found in a `*.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 `sys.path` is a sequence. Items of `sys.path` that are not strings referring to existing directories are ignored. Unicode items on `sys.path` that cause errors when used as filenames may cause this function to raise an exception (in line with `os.path.isdir()` behavior).

`pkgutil.``get_data`(package, resource)

  Get a resource from a package.

  This is a wrapper for the PEP 302 loader `get_data()` API. The package argument should be the name of a package, in standard module format (foo.bar). The resource argument should be in the form of a relative filename, using `/` as the path separator. The parent directory name `..` is not allowed, and nor is a rooted name (starting with a `/`).

  The function returns a binary string that is the contents of the specified resource.

  For packages located in the filesystem, which have already been imported, this is the rough equivalent of:

      d = os.path.dirname(sys.modules[package].__file__)
      data = open(os.path.join(d, resource), 'rb').read()

  If the package cannot be located or loaded, or it uses a PEP 302 loader which does not support `get_data()`, then None is returned.

### Navigation

- index
- modules |
- next |
- previous |
- Python v3.1a1 documentation »
- The Python Standard Library »
- Importing Modules »