| 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 |