Mercurial > cpython-lru_cache-weakref

annotate Doc/library/pkgutil.rst @ 54294:dba767bc3155 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
remove mention of old ctypes version
author Benjamin Peterson <benjamin@python.org>
date Sat, 23 May 2009 20:59:09 +0000
parents df13ccaa5ae9
children 742f19b47020
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2 :mod:`pkgutil` --- Package extension utility
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 ============================================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 .. module:: pkgutil
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 :synopsis: Utilities to support extension of packages.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
46454
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
11 This module provides functions to manipulate packages:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 .. function:: extend_path(path, name)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16 Extend the search path for the modules which comprise a package. Intended use is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 to place the following code in a package's :file:`__init__.py`::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 from pkgutil import extend_path
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 __path__ = extend_path(__path__, __name__)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 This will add to the package's ``__path__`` all subdirectories of directories on
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 ``sys.path`` named after the package. This is useful if one wants to distribute
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24 different parts of a single logical package as multiple directories.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 It also looks for :file:`\*.pkg` files beginning where ``*`` matches the *name*
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 argument. This feature is similar to :file:`\*.pth` files (see the :mod:`site`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 module for more information), except that it doesn't special-case lines starting
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 with ``import``. A :file:`\*.pkg` file is trusted at face value: apart from
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 checking for duplicates, all entries found in a :file:`\*.pkg` file are added to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 the path, regardless of whether they exist on the filesystem. (This is a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 feature.)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 If the input path is not a list (as is the case for frozen packages) it is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 returned unchanged. The input path is not modified; an extended copy is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 returned. Items are only appended to the copy at the end.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38 It is assumed that ``sys.path`` is a sequence. Items of ``sys.path`` that are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 not (Unicode or 8-bit) strings referring to existing directories are ignored.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 Unicode items on ``sys.path`` that cause errors when used as filenames may cause
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 this function to raise an exception (in line with :func:`os.path.isdir`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 behavior).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
46454
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
44 .. function:: get_data(package, resource)
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
45
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
46 Get a resource from a package.
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
47
46511
df13ccaa5ae9 Wording changes
Andrew M. Kuchling <amk@amk.ca>
parents: 46454
diff changeset
48 This is a wrapper for the PEP 302 loader :func:`get_data` API. The package
46454
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
49 argument should be the name of a package, in standard module format
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
50 (foo.bar). The resource argument should be in the form of a relative
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
51 filename, using ``/`` as the path separator. The parent directory name
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
52 ``..`` is not allowed, and nor is a rooted name (starting with a ``/``).
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
53
46511
df13ccaa5ae9 Wording changes
Andrew M. Kuchling <amk@amk.ca>
parents: 46454
diff changeset
54 The function returns a binary string that is the contents of the
46454
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
55 specified resource.
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
56
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
57 For packages located in the filesystem, which have already been imported,
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
58 this is the rough equivalent of::
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
59
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
60 d = os.path.dirname(sys.modules[package].__file__)
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
61 data = open(os.path.join(d, resource), 'rb').read()
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
62
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
63 If the package cannot be located or loaded, or it uses a PEP 302 loader
1841f92e30de Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
Nick Coghlan <ncoghlan@gmail.com>
parents: 42604
diff changeset
64 which does not support :func:`get_data`, then None is returned.