1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
.. _migration:
=================
Migration guide
=================
The following guide will help you migrate common ``pkg_resources``
APIs to ``importlib_metadata``. ``importlib_metadata`` aims to
replace the following ``pkg_resources`` APIs:
* ``pkg_resources.iter_entry_points()``
* ``pkg_resources.require()``
* convenience functions
* ``pkg_resources.find_distributions()``
* ``pkg_resources.get_distribution()``
Other functionality from ``pkg_resources`` is replaced by other
packages such as
`importlib_resources <https://pypi.org/project/importlib_resources>`_
and `packaging <https://pypi.org/project/packaging>`_.
pkg_resources.iter_entry_points()
=================================
``importlib_metadata`` provides :ref:`entry-points`.
Compatibility note: entry points provided by importlib_metadata
do not have the following implicit behaviors found in those
from ``pkg_resources``:
- Each EntryPoint is not automatically validated to match. To
ensure each one is validated, invoke any property on the
object (e.g. ``ep.name``).
- When invoking ``EntryPoint.load()``, no checks are performed
to ensure the declared extras are installed. If this behavior
is desired/required, it is left to the user to perform the
check and install any dependencies. See
`importlib_metadata#368 <https://github.com/python/importlib_metadata/issues/368>`_
for more details.
pkg_resources.require()
=======================
``importlib_metadata`` does not provide support for dynamically
discovering or requiring distributions nor does it provide any
support for managing the "working set". Furthermore,
``importlib_metadata`` assumes that only one version of a given
distribution is discoverable at any time (no support for multi-version
installs). Any projects that require the above behavior needs to
provide that behavior independently.
``importlib_metadata`` does aim to resolve metadata concerns late
such that any dynamic changes to package availability should be
reflected immediately.
Convenience functions
=====================
In addition to the support for direct access to ``Distribution``
objects (below), ``importlib_metadata`` presents some top-level
functions for easy access to the most common metadata:
- :ref:`metadata` queries the metadata fields from the distribution.
- :ref:`version` provides quick access to the distribution version.
- :ref:`requirements` presents the requirements of the distribution.
- :ref:`files` provides file-like access to the data blobs backing
the metadata.
pkg_resources.find_distributions()
==================================
``importlib_metadata`` provides functionality
similar to ``find_distributions()``. Both ``distributions(...)`` and
``Distribution.discover(...)`` return an iterable of :ref:`distributions`
matching the indicated parameters.
pkg_resources.get_distribution()
=================================
Similar to ``distributions``, the ``distribution()`` function provides
access to a single distribution by name.
|
