migration.rst

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