1 \section{\module{pkgutil
} ---
2 Package extension utility
}
4 \declaremodule{standard
}{pkgutil
}
5 \modulesynopsis{Utilities to support extension of packages.
}
9 This module provides a single function:
11 \begin{funcdesc
}{extend_path
}{path, name
}
12 Extend the search path for the modules which comprise a package.
13 Intended use is to place the following code in a package's
17 from pkgutil import extend_path
18 __path__ = extend_path(__path__, __name__)
21 This will add to the package's
\code{__path__
} all subdirectories of
22 directories on
\code{sys.path
} named after the package. This is
23 useful if one wants to distribute different parts of a single
24 logical package as multiple directories.
26 It also looks for
\file{*.pkg
} files beginning where
\code{*
}
27 matches the
\var{name
} argument. This feature is similar to
28 \file{*.pth
} files (see the
\refmodule{site
} module for more
29 information), except that it doesn't special-case lines starting
30 with
\code{import
}. A
\file{*.pkg
} file is trusted at face value:
31 apart from checking for duplicates, all entries found in a
32 \file{*.pkg
} file are added to the path, regardless of whether they
33 exist on the filesystem. (This is a feature.)
35 If the input path is not a list (as is the case for frozen
36 packages) it is returned unchanged. The input path is not
37 modified; an extended copy is returned. Items are only appended
38 to the copy at the end.
40 It is assumed that
\code{sys.path
} is a sequence. Items of
41 \code{sys.path
} that are not (Unicode or
8-bit) strings referring to
42 existing directories are ignored. Unicode items on
\code{sys.path
}
43 that cause errors when used as filenames may cause this function to
44 raise an exception (in line with
\function{os.path.isdir()
} behavior).