rest25/library/pkgutil.rst => rest262/library/pkgutil.rst
3============================================
4
5.. module:: pkgutil
6   :synopsis: Utilities to support extension of packages.
7
8
9.. versionadded:: 2.3
10
n11-This module provides a single function:
n11+This module provides functions to manipulate packages:
12
13
14.. function:: extend_path(path, name)
15
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:`__init__.py`::
18
19      from pkgutil import extend_path
36   returned.  Items are only appended to the copy at the end.
37
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).
43
t44+.. function:: get_data(package, resource)
45+ 
46+   Get a resource from a package.
47+ 
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+   (foo.bar). 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 ``/``).
53+ 
54+   The function returns a binary string that is the contents of the
55+   specified resource.
56+ 
57+   For packages located in the filesystem, which have already been imported,
58+   this is the rough equivalent of::
59+ 
60+       d = os.path.dirname(sys.modules[package].__file__)
61+       data = open(os.path.join(d, resource), 'rb').read()
62+ 
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.
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op