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 .. function:: find_loader(fullname)
53
54 Retrieve a module :term:`loader` for the given *fullname*.
55
56 This is a backwards compatibility wrapper around
57 :func:`importlib.util.find_spec` that converts most failures to
58 :exc:`ImportError` and only returns the loader rather than the full
59 :class:`importlib.machinery.ModuleSpec`.
60
61 .. versionchanged:: 3.3
62 Updated to be based directly on :mod:`importlib` rather than relying
63 on the package internal :pep:`302` import emulation.
64
65 .. versionchanged:: 3.4
66 Updated to be based on :pep:`451`
67
68 .. deprecated-removed:: 3.12 3.14
69 Use :func:`importlib.util.find_spec` instead.
70
71
72 .. function:: get_importer(path_item)
73
74 Retrieve a :term:`finder` for the given *path_item*.
75
76 The returned finder is cached in :data:`sys.path_importer_cache` if it was
77 newly created by a path hook.
78
79 The cache (or part of it) can be cleared manually if a rescan of
80 :data:`sys.path_hooks` is necessary.
81
82 .. versionchanged:: 3.3
83 Updated to be based directly on :mod:`importlib` rather than relying
84 on the package internal :pep:`302` import emulation.
85
86
87 .. function:: get_loader(module_or_name)
88
89 Get a :term:`loader` object for *module_or_name*.
90
91 If the module or package is accessible via the normal import mechanism, a
92 wrapper around the relevant part of that machinery is returned. Returns
93 ``None`` if the module cannot be found or imported. If the named module is
94 not already imported, its containing package (if any) is imported, in order
95 to establish the package ``__path__``.
96
97 .. versionchanged:: 3.3
98 Updated to be based directly on :mod:`importlib` rather than relying
99 on the package internal :pep:`302` import emulation.
100
101 .. versionchanged:: 3.4
102 Updated to be based on :pep:`451`
103
104 .. deprecated-removed:: 3.12 3.14
105 Use :func:`importlib.util.find_spec` instead.
106
107
108 .. function:: iter_importers(fullname='')
109
110 Yield :term:`finder` objects for the given module name.
111
112 If *fullname* contains a ``'.'``, the finders will be for the package
113 containing *fullname*, otherwise they will be all registered top level
114 finders (i.e. those on both :data:`sys.meta_path` and :data:`sys.path_hooks`).
115
116 If the named module is in a package, that package is imported as a side
117 effect of invoking this function.
118
119 If no module name is specified, all top level finders are produced.
120
121 .. versionchanged:: 3.3
122 Updated to be based directly on :mod:`importlib` rather than relying
123 on the package internal :pep:`302` import emulation.
124
125
126 .. function:: iter_modules(path=None, prefix='')
127
128 Yields :class:`ModuleInfo` for all submodules on *path*, or, if
129 *path* is ``None``, all top-level modules on :data:`sys.path`.
130
131 *path* should be either ``None`` or a list of paths to look for modules in.
132
133 *prefix* is a string to output on the front of every module name on output.
134
135 .. note::
136
137 Only works for a :term:`finder` which defines an ``iter_modules()``
138 method. This interface is non-standard, so the module also provides
139 implementations for :class:`importlib.machinery.FileFinder` and
140 :class:`zipimport.zipimporter`.
141
142 .. versionchanged:: 3.3
143 Updated to be based directly on :mod:`importlib` rather than relying
144 on the package internal :pep:`302` import emulation.
145
146
147 .. function:: walk_packages(path=None, prefix='', onerror=None)
148
149 Yields :class:`ModuleInfo` for all modules recursively on
150 *path*, or, if *path* is ``None``, all accessible modules.
151
152 *path* should be either ``None`` or a list of paths to look for modules in.
153
154 *prefix* is a string to output on the front of every module name on output.
155
156 Note that this function must import all *packages* (*not* all modules!) on
157 the given *path*, in order to access the ``__path__`` attribute to find
158 submodules.
159
160 *onerror* is a function which gets called with one argument (the name of the
161 package which was being imported) if any exception occurs while trying to
162 import a package. If no *onerror* function is supplied, :exc:`ImportError`\s
163 are caught and ignored, while all other exceptions are propagated,
164 terminating the search.
165
166 Examples::
167
168 # list all modules python can access
169 walk_packages()
170
171 # list all submodules of ctypes
172 walk_packages(ctypes.__path__, ctypes.__name__ + '.')
173
174 .. note::
175
176 Only works for a :term:`finder` which defines an ``iter_modules()``
177 method. This interface is non-standard, so the module also provides
178 implementations for :class:`importlib.machinery.FileFinder` and
179 :class:`zipimport.zipimporter`.
180
181 .. versionchanged:: 3.3
182 Updated to be based directly on :mod:`importlib` rather than relying
183 on the package internal :pep:`302` import emulation.
184
185
186 .. function:: get_data(package, resource)
187
188 Get a resource from a package.
189
190 This is a wrapper for the :term:`loader`
191 :meth:`get_data <importlib.abc.ResourceLoader.get_data>` API. The
192 *package* argument should be the name of a package, in standard module format
193 (``foo.bar``). The *resource* argument should be in the form of a relative
194 filename, using ``/`` as the path separator.
195
196 The function returns a binary string that is the contents of the specified
197 resource.
198
199 This function uses the :term:`loader` method
200 :func:`~importlib.abc.FileLoader.get_data`
201 to support modules installed in the filesystem, but also in zip files,
202 databases, or elsewhere.
203
204 For packages located in the filesystem, which have already been imported,
205 this is the rough equivalent of::
206
207 d = os.path.dirname(sys.modules[package].__file__)
208 data = open(os.path.join(d, resource), 'rb').read()
209
210 Like the :func:`open` function, :func:`!get_data` can follow parent
211 directories (``../``) and absolute paths (starting with ``/`` or ``C:/``,
212 for example).
213 It can open compilation/installation artifacts like ``.py`` and ``.pyc``
214 files or files with :func:`reserved filenames <os.path.isreserved>`.
215 To be compatible with non-filesystem loaders, avoid using these features.
216
217 .. warning::
218
219 This function is intended for trusted input.
220 It does not verify that *resource* "belongs" to *package*.
221
222 If you use a user-provided *resource* path, consider verifying it.
223 For example, require an alphanumeric filename with a known extension, or
224 install and check a list of known resources.
225
226 If the package cannot be located or loaded, or it uses a :term:`loader`
227 which does not support :meth:`get_data <importlib.abc.ResourceLoader.get_data>`,
228 then ``None`` is returned. In particular, the :term:`loader` for
229 :term:`namespace packages <namespace package>` does not support
230 :meth:`get_data <importlib.abc.ResourceLoader.get_data>`.
231
232 .. seealso::
233
234 The :mod:`importlib.resources` module provides structured access to
235 module resources.
236
237 .. function:: resolve_name(name)
238
239 Resolve a name to an object.
240
241 This functionality is used in numerous places in the standard library (see
242 :issue:`12915`) - and equivalent functionality is also in widely used
243 third-party packages such as setuptools, Django and Pyramid.
244
245 It is expected that *name* will be a string in one of the following
246 formats, where W is shorthand for a valid Python identifier and dot stands
247 for a literal period in these pseudo-regexes:
248
249 * ``W(.W)*``
250 * ``W(.W)*:(W(.W)*)?``
251
252 The first form is intended for backward compatibility only. It assumes that
253 some part of the dotted name is a package, and the rest is an object
254 somewhere within that package, possibly nested inside other objects.
255 Because the place where the package stops and the object hierarchy starts
256 can't be inferred by inspection, repeated attempts to import must be done
257 with this form.
258
259 In the second form, the caller makes the division point clear through the
260 provision of a single colon: the dotted name to the left of the colon is a
261 package to be imported, and the dotted name to the right is the object
262 hierarchy within that package. Only one import is needed in this form. If
263 it ends with the colon, then a module object is returned.
264
265 The function will return an object (which might be a module), or raise one
266 of the following exceptions:
267
268 :exc:`ValueError` -- if *name* isn't in a recognised format.
269
270 :exc:`ImportError` -- if an import failed when it shouldn't have.
271
272 :exc:`AttributeError` -- If a failure occurred when traversing the object
273 hierarchy within the imported package to get to the desired object.
274
275 .. versionadded:: 3.9