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
and packaging.
pkg_resources.iter_entry_points()#
importlib_metadata
provides 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 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:
Distribution metadata queries the metadata fields from the distribution.
Distribution versions provides quick access to the distribution version.
Distribution requirements presents the requirements of the distribution.
Distribution 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 Distributions
matching the indicated parameters.
pkg_resources.get_distribution()#
Similar to distributions
, the distribution()
function provides
access to a single distribution by name.