Mercurial > cpython-lru_cache-weakref

annotate Doc/library/pkgutil.rst @ 79675:c0a2294de787 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16199: Backport 2to3 typo fix from 3.2.
author Chris Jerdonek <chris.jerdonek@gmail.com>
date Thu, 11 Oct 2012 16:15:46 -0700
parents 4c6b1b2d481a
children
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 :mod:`pkgutil` --- Package extension utility
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2 ============================================
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 .. module:: pkgutil
66453
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
5 :synopsis: Utilities for the import system.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
71952
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 66945
diff changeset
7 .. versionadded:: 2.3
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 66945
diff changeset
8
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 66945
diff changeset
9 **Source code:** :source:`Lib/pkgutil.py`
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 66945
diff changeset
10
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 66945
diff changeset
11 --------------
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 66945
diff changeset
12
66453
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
13 This module provides utilities for the import system, in particular package
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
14 support.
42604
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 .. function:: extend_path(path, name)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
66453
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
19 Extend the search path for the modules which comprise a package. Intended
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
20 use is to place the following code in a package's :file:`__init__.py`::
42604
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 from pkgutil import extend_path
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 __path__ = extend_path(__path__, __name__)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24
66453
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
25 This will add to the package's ``__path__`` all subdirectories of directories
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
26 on ``sys.path`` named after the package. This is useful if one wants to
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
27 distribute different parts of a single logical package as multiple
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
28 directories.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29
66453
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
30 It also looks for :file:`\*.pkg` files beginning where ``*`` matches the
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
31 *name* argument. This feature is similar to :file:`\*.pth` files (see the
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
32 :mod:`site` module for more information), except that it doesn't special-case
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
33 lines starting with ``import``. A :file:`\*.pkg` file is trusted at face
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
34 value: apart from checking for duplicates, all entries found in a
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
35 :file:`\*.pkg` file are added to the path, regardless of whether they exist
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
36 on the filesystem. (This is a feature.)
42604
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 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
39 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
40 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
41
66453
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
42 It is assumed that :data:`sys.path` is a sequence. Items of :data:`sys.path`
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
43 that are not (Unicode or 8-bit) strings referring to existing directories are
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
44 ignored. Unicode items on :data:`sys.path` that cause errors when used as
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
45 filenames may cause this function to raise an exception (in line with
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
46 :func:`os.path.isdir` behavior).
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
47
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
48
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
49 .. class:: ImpImporter(dirname=None)
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
50
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
51 :pep:`302` Importer that wraps Python's "classic" import algorithm.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
52
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
53 If *dirname* is a string, a :pep:`302` importer is created that searches that
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
54 directory. If *dirname* is ``None``, a :pep:`302` importer is created that
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
55 searches the current :data:`sys.path`, plus any modules that are frozen or
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
56 built-in.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
57
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
58 Note that :class:`ImpImporter` does not currently support being used by
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
59 placement on :data:`sys.meta_path`.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
60
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
61
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
62 .. class:: ImpLoader(fullname, file, filename, etc)
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
63
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
64 :pep:`302` Loader that wraps Python's "classic" import algorithm.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
65
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
66
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
67 .. function:: find_loader(fullname)
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
68
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
69 Find a :pep:`302` "loader" object for *fullname*.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
70
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
71 If *fullname* contains dots, path must be the containing package's
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
72 ``__path__``. Returns ``None`` if the module cannot be found or imported.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
73 This function uses :func:`iter_importers`, and is thus subject to the same
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
74 limitations regarding platform-specific special import locations such as the
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
75 Windows registry.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
76
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
77
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
78 .. function:: get_importer(path_item)
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
79
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
80 Retrieve a :pep:`302` importer for the given *path_item*.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
81
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
82 The returned importer is cached in :data:`sys.path_importer_cache` if it was
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
83 newly created by a path hook.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
84
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
85 If there is no importer, a wrapper around the basic import machinery is
66945
56999495a9ba Merged revisions 87289 via svnmerge from
Éric Araujo <merwok@netwok.org>
parents: 66453
diff changeset
86 returned. This wrapper is never inserted into the importer cache (``None``
56999495a9ba Merged revisions 87289 via svnmerge from
Éric Araujo <merwok@netwok.org>
parents: 66453
diff changeset
87 is inserted instead).
66453
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
88
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
89 The cache (or part of it) can be cleared manually if a rescan of
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
90 :data:`sys.path_hooks` is necessary.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
91
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
92
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
93 .. function:: get_loader(module_or_name)
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
94
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
95 Get a :pep:`302` "loader" object for *module_or_name*.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
96
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
97 If the module or package is accessible via the normal import mechanism, a
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
98 wrapper around the relevant part of that machinery is returned. Returns
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
99 ``None`` if the module cannot be found or imported. If the named module is
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
100 not already imported, its containing package (if any) is imported, in order
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
101 to establish the package ``__path__``.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
102
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
103 This function uses :func:`iter_importers`, and is thus subject to the same
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
104 limitations regarding platform-specific special import locations such as the
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
105 Windows registry.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
106
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
107
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
108 .. function:: iter_importers(fullname='')
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
109
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
110 Yield :pep:`302` importers for the given module name.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
111
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
112 If fullname contains a '.', the importers will be for the package containing
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
113 fullname, otherwise they will be importers for :data:`sys.meta_path`,
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
114 :data:`sys.path`, and Python's "classic" import machinery, in that order. If
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
115 the named module is in a package, that package is imported as a side effect
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
116 of invoking this function.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
117
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
118 Non-:pep:`302` mechanisms (e.g. the Windows registry) used by the standard
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
119 import machinery to find files in alternative locations are partially
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
120 supported, but are searched *after* :data:`sys.path`. Normally, these
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
121 locations are searched *before* :data:`sys.path`, preventing :data:`sys.path`
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
122 entries from shadowing them.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
123
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
124 For this to cause a visible difference in behaviour, there must be a module
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
125 or package name that is accessible via both :data:`sys.path` and one of the
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
126 non-:pep:`302` file system mechanisms. In this case, the emulation will find
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
127 the former version, while the builtin import mechanism will find the latter.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
128
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
129 Items of the following types can be affected by this discrepancy:
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
130 ``imp.C_EXTENSION``, ``imp.PY_SOURCE``, ``imp.PY_COMPILED``,
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
131 ``imp.PKG_DIRECTORY``.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
132
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
133
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
134 .. function:: iter_modules(path=None, prefix='')
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
135
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
136 Yields ``(module_loader, name, ispkg)`` for all submodules on *path*, or, if
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
137 path is ``None``, all top-level modules on ``sys.path``.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
138
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
139 *path* should be either ``None`` or a list of paths to look for modules in.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
140
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
141 *prefix* is a string to output on the front of every module name on output.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
142
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
143
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
144 .. function:: walk_packages(path=None, prefix='', onerror=None)
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
145
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
146 Yields ``(module_loader, name, ispkg)`` for all modules recursively on
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
147 *path*, or, if path is ``None``, all accessible modules.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
148
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
149 *path* should be either ``None`` or a list of paths to look for modules in.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
150
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
151 *prefix* is a string to output on the front of every module name on output.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
152
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
153 Note that this function must import all *packages* (*not* all modules!) on
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
154 the given *path*, in order to access the ``__path__`` attribute to find
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
155 submodules.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
156
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
157 *onerror* is a function which gets called with one argument (the name of the
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
158 package which was being imported) if any exception occurs while trying to
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
159 import a package. If no *onerror* function is supplied, :exc:`ImportError`\s
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
160 are caught and ignored, while all other exceptions are propagated,
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
161 terminating the search.
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
162
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
163 Examples::
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
164
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
165 # list all modules python can access
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
166 walk_packages()
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
167
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
168 # list all submodules of ctypes
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
169 walk_packages(ctypes.__path__, ctypes.__name__ + '.')
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
170
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
171
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
172 .. 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
173
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
174 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
175
66453
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
176 This is a wrapper for the :pep:`302` loader :func:`get_data` API. The
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
177 *package* argument should be the name of a package, in standard module format
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
178 (``foo.bar``). The *resource* argument should be in the form of a relative
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
179 filename, using ``/`` as the path separator. The parent directory name
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
180 ``..`` 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
181
66453
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
182 The function returns a binary string that is the contents of the specified
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
183 resource.
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
184
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
185 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
186 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
187
66453
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
188 d = os.path.dirname(sys.modules[package].__file__)
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
189 data = open(os.path.join(d, resource), 'rb').read()
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
190
61571
742f19b47020 Doc: replace PEP xxx by :pep:`xxx` to create a link on the PEP
Victor Stinner <victor.stinner@haypocalc.com>
parents: 46511
diff changeset
191 If the package cannot be located or loaded, or it uses a :pep:`302` loader
66453
8ce9ae5a1542 Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61571
diff changeset
192 which does not support :func:`get_data`, then ``None`` is returned.
72138
4c6b1b2d481a added versionadd information for pkgutil.get_data(); thanks to Kyle Monson from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents: 71952
diff changeset
193
4c6b1b2d481a added versionadd information for pkgutil.get_data(); thanks to Kyle Monson from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents: 71952
diff changeset
194 .. versionadded:: 2.6