3.22 pkgutil -- Package extension utility

New in version 2.3.

This module provides a single function:

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 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 (Unicode or 8-bit) 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).

---

Python Library Reference

Previous: 3.21.1 Examples Up: 3. Python Runtime Services Next: 3.23 code

---

Release 2.4, documentation updated on 29 November 2004.