Debian Codegraph @

Doc/library/pkgutil.rst

raw
1 :mod:`!pkgutil` --- Package extension utility
2 =============================================
3
4 .. module:: pkgutil
5 :synopsis: Utilities for the import system.
6
7 **Source code:** :source:`Lib/pkgutil.py`
8
9 --------------
10
11 This module provides utilities for the import system, in particular package
12 support.
13
14 .. class:: ModuleInfo(module_finder, name, ispkg)
15
16 A namedtuple that holds a brief summary of a module's info.
17
18 .. versionadded:: 3.6
19
20 .. function:: extend_path(path, name)
21
22 Extend the search path for the modules which comprise a package. Intended
23 use is to place the following code in a package's :file:`__init__.py`::
24
25 from pkgutil import extend_path
26 __path__ = extend_path(__path__, __name__)
27
28 For each directory on :data:`sys.path` that has a subdirectory that matches the
29 package name, add the subdirectory to the package's
30 :attr:`~module.__path__`. This is useful
31 if one wants to distribute different parts of a single logical package as multiple
32 directories.
33
34 It also looks for :file:`\*.pkg` files beginning where ``*`` matches the
35 *name* argument. This feature is similar to :file:`\*.pth` files (see the
36 :mod:`site` module for more information), except that it doesn't special-case
37 lines starting with ``import``. A :file:`\*.pkg` file is trusted at face
38 value: apart from skipping blank lines and ignoring comments, all entries
39 found in a :file:`\*.pkg` file are added to the path, regardless of whether
40 they exist on the filesystem (this is a feature).
41
42 If the input path is not a list (as is the case for frozen packages) it is
43 returned unchanged. The input path is not modified; an extended copy is
44 returned. Items are only appended to the copy at the end.
45
46 It is assumed that :data:`sys.path` is a sequence. Items of :data:`sys.path`
47 that are not strings referring to existing directories are ignored. Unicode
48 items on :data:`sys.path` that cause errors when used as filenames may cause
49 this function to raise an exception (in line with :func:`os.path.isdir`
50 behavior).
51
52
53 .. function:: get_importer(path_item)
54
55 Retrieve a :term:`finder` for the given *path_item*.
56
57 The returned finder is cached in :data:`sys.path_importer_cache` if it was
58 newly created by a path hook.
59
60 The cache (or part of it) can be cleared manually if a rescan of
61 :data:`sys.path_hooks` is necessary.
62
63 .. versionchanged:: 3.3
64 Updated to be based directly on :mod:`importlib` rather than relying
65 on the package internal :pep:`302` import emulation.
66
67
68 .. function:: iter_importers(fullname='')
69
70 Yield :term:`finder` objects for the given module name.
71
72 If *fullname* contains a ``'.'``, the finders will be for the package
73 containing *fullname*, otherwise they will be all registered top level
74 finders (i.e. those on both :data:`sys.meta_path` and :data:`sys.path_hooks`).
75
76 If the named module is in a package, that package is imported as a side
77 effect of invoking this function.
78
79 If no module name is specified, all top level finders are produced.
80
81 .. versionchanged:: 3.3
82 Updated to be based directly on :mod:`importlib` rather than relying
83 on the package internal :pep:`302` import emulation.
84
85
86 .. function:: iter_modules(path=None, prefix='')
87
88 Yields :class:`ModuleInfo` for all submodules on *path*, or, if
89 *path* is ``None``, all top-level modules on :data:`sys.path`.
90
91 *path* should be either ``None`` or a list of paths to look for modules in.
92
93 *prefix* is a string to output on the front of every module name on output.
94
95 .. note::
96
97 Only works for a :term:`finder` which defines an ``iter_modules()``
98 method. This interface is non-standard, so the module also provides
99 implementations for :class:`importlib.machinery.FileFinder` and
100 :class:`zipimport.zipimporter`.
101
102 .. versionchanged:: 3.3
103 Updated to be based directly on :mod:`importlib` rather than relying
104 on the package internal :pep:`302` import emulation.
105
106
107 .. function:: walk_packages(path=None, prefix='', onerror=None)
108
109 Yields :class:`ModuleInfo` for all modules recursively on
110 *path*, or, if *path* is ``None``, all accessible modules.
111
112 *path* should be either ``None`` or a list of paths to look for modules in.
113
114 *prefix* is a string to output on the front of every module name on output.
115
116 Note that this function must import all *packages* (*not* all modules!) on
117 the given *path*, in order to access the ``__path__`` attribute to find
118 submodules.
119
120 *onerror* is a function which gets called with one argument (the name of the
121 package which was being imported) if any exception occurs while trying to
122 import a package. If no *onerror* function is supplied, :exc:`ImportError`\s
123 are caught and ignored, while all other exceptions are propagated,
124 terminating the search.
125
126 Examples::
127
128 # list all modules python can access
129 walk_packages()
130
131 # list all submodules of ctypes
132 walk_packages(ctypes.__path__, ctypes.__name__ + '.')
133
134 .. note::
135
136 Only works for a :term:`finder` which defines an ``iter_modules()``
137 method. This interface is non-standard, so the module also provides
138 implementations for :class:`importlib.machinery.FileFinder` and
139 :class:`zipimport.zipimporter`.
140
141 .. versionchanged:: 3.3
142 Updated to be based directly on :mod:`importlib` rather than relying
143 on the package internal :pep:`302` import emulation.
144
145
146 .. function:: get_data(package, resource)
147
148 Get a resource from a package.
149
150 This is a wrapper for the :term:`loader`
151 :meth:`get_data <importlib.abc.ResourceLoader.get_data>` API. The
152 *package* argument should be the name of a package, in standard module format
153 (``foo.bar``). The *resource* argument should be in the form of a relative
154 filename, using ``/`` as the path separator.
155
156 The function returns a binary string that is the contents of the specified
157 resource.
158
159 This function uses the :term:`loader` method
160 :func:`~importlib.abc.FileLoader.get_data`
161 to support modules installed in the filesystem, but also in zip files,
162 databases, or elsewhere.
163
164 For packages located in the filesystem, which have already been imported,
165 this is the rough equivalent of::
166
167 d = os.path.dirname(sys.modules[package].__file__)
168 data = open(os.path.join(d, resource), 'rb').read()
169
170 Like the :func:`open` function, :func:`!get_data` can follow parent
171 directories (``../``) and absolute paths (starting with ``/`` or ``C:/``,
172 for example).
173 It can open compilation/installation artifacts like ``.py`` and ``.pyc``
174 files or files with :func:`reserved filenames <os.path.isreserved>`.
175 To be compatible with non-filesystem loaders, avoid using these features.
176
177 .. warning::
178
179 This function is intended for trusted input.
180 It does not verify that *resource* "belongs" to *package*.
181
182 If you use a user-provided *resource* path, consider verifying it.
183 For example, require an alphanumeric filename with a known extension, or
184 install and check a list of known resources.
185
186 If the package cannot be located or loaded, or it uses a :term:`loader`
187 which does not support :meth:`get_data <importlib.abc.ResourceLoader.get_data>`,
188 then ``None`` is returned. In particular, the :term:`loader` for
189 :term:`namespace packages <namespace package>` does not support
190 :meth:`get_data <importlib.abc.ResourceLoader.get_data>`.
191
192 .. seealso::
193
194 The :mod:`importlib.resources` module provides structured access to
195 module resources.
196
197 .. function:: resolve_name(name)
198
199 Resolve a name to an object.
200
201 This functionality is used in numerous places in the standard library (see
202 :issue:`12915`) - and equivalent functionality is also in widely used
203 third-party packages such as setuptools, Django and Pyramid.
204
205 It is expected that *name* will be a string in one of the following
206 formats, where W is shorthand for a valid Python identifier and dot stands
207 for a literal period in these pseudo-regexes:
208
209 * ``W(.W)*``
210 * ``W(.W)*:(W(.W)*)?``
211
212 The first form is intended for backward compatibility only. It assumes that
213 some part of the dotted name is a package, and the rest is an object
214 somewhere within that package, possibly nested inside other objects.
215 Because the place where the package stops and the object hierarchy starts
216 can't be inferred by inspection, repeated attempts to import must be done
217 with this form.
218
219 In the second form, the caller makes the division point clear through the
220 provision of a single colon: the dotted name to the left of the colon is a
221 package to be imported, and the dotted name to the right is the object
222 hierarchy within that package. Only one import is needed in this form. If
223 it ends with the colon, then a module object is returned.
224
225 The function will return an object (which might be a module), or raise one
226 of the following exceptions:
227
228 :exc:`ValueError` -- if *name* isn't in a recognised format.
229
230 :exc:`ImportError` -- if an import failed when it shouldn't have.
231
232 :exc:`AttributeError` -- If a failure occurred when traversing the object
233 hierarchy within the imported package to get to the desired object.
234
235 .. versionadded:: 3.9