API Reference

importlib_metadata module

class importlib_metadata.Distribution

Bases: object

A Python distribution package.

static at(path)

Return a Distribution for the indicated metadata path

Parameters

path – a string or path-like object

Returns

a concrete Distribution instance for the path

classmethod discover(**kwargs)

Return an iterable of Distribution objects for all packages.

Pass a context or pass keyword arguments for constructing a context.

Context

A DistributionFinder.Context object.

Returns

Iterable of Distribution objects for all packages.

property entry_points
property files

Files in this distribution.

Returns

List of PackagePath for this distribution or None

Result is None if the metadata file that enumerates files (i.e. RECORD for dist-info or SOURCES.txt for egg-info) is missing. Result may be empty if the metadata exists but is empty.

classmethod from_name(name)

Return the Distribution for the given package name.

Parameters

name – The name of the distribution package to search for.

Returns

The Distribution instance (or subclass thereof) for the named package, if found.

Raises

PackageNotFoundError – When the named package’s distribution metadata cannot be found.

abstract locate_file(path)

Given a path to a file in this distribution, return a path to it.

property metadata: importlib_metadata._meta.PackageMetadata

Return the parsed metadata for this Distribution.

The returned object will have keys that name the various bits of metadata. See PEP 566 for details.

property name

Return the ‘Name’ metadata for the distribution package.

abstract read_text(filename)

Attempt to load metadata file given by the name.

Parameters

filename – The name of the file in the distribution info.

Returns

The text if found, otherwise None.

property requires

Generated requirements specified for this Distribution

property version

Return the ‘Version’ metadata for the distribution package.

class importlib_metadata.DistributionFinder

Bases: importlib.abc.MetaPathFinder

A MetaPathFinder capable of discovering installed distributions.

class Context(**kwargs)

Bases: object

Keyword arguments presented by the caller to distributions() or Distribution.discover() to narrow the scope of a search for distributions in all DistributionFinders.

Each DistributionFinder may expect any parameters and should attempt to honor the canonical parameters defined below when appropriate.

name = None

Specific name for which a distribution finder should match. A name of None matches all distributions.

property path

The sequence of directory path that a distribution finder should search.

Typically refers to Python installed package paths such as “site-packages” directories and defaults to sys.path.

abstract find_distributions(context=<importlib_metadata.DistributionFinder.Context object>)

Find distributions.

Return an iterable of all Distribution instances capable of loading the metadata for packages matching the context, a DistributionFinder.Context instance.

class importlib_metadata.PackageMetadata(*args, **kwds)

Bases: typing_extensions.Protocol

get_all(name: str, failobj: importlib_metadata._meta._T = Ellipsis) Union[List[Any], importlib_metadata._meta._T]

Return all values associated with a possibly multi-valued key.

property json: Dict[str, Union[str, List[str]]]

A JSON-compatible form of the metadata.

exception importlib_metadata.PackageNotFoundError

Bases: ModuleNotFoundError

The package was not found.

property name

module name

importlib_metadata.distribution(distribution_name)

Get the Distribution instance for the named package.

Parameters

distribution_name – The name of the distribution package as a string.

Returns

A Distribution instance (or subclass thereof).

importlib_metadata.distributions(**kwargs)

Get all Distribution instances in the current environment.

Returns

An iterable of Distribution instances.

importlib_metadata.entry_points(**params) Union[importlib_metadata.EntryPoints, importlib_metadata.SelectableGroups]

Return EntryPoint objects for all installed packages.

Pass selection parameters (group or name) to filter the result to entry points matching those properties (see EntryPoints.select()).

For compatibility, returns SelectableGroups object unless selection parameters are supplied. In the future, this function will return EntryPoints instead of SelectableGroups even when no selection parameters are supplied.

For maximum future compatibility, pass selection parameters or invoke .select with parameters on the result.

Returns

EntryPoints or SelectableGroups for all installed packages.

importlib_metadata.files(distribution_name)

Return a list of files for the named package.

Parameters

distribution_name – The name of the distribution package to query.

Returns

List of files composing the distribution.

importlib_metadata.metadata(distribution_name) importlib_metadata._meta.PackageMetadata

Get the metadata for the named package.

Parameters

distribution_name – The name of the distribution package to query.

Returns

A PackageMetadata containing the parsed metadata.

importlib_metadata.packages_distributions() Mapping[str, List[str]]

Return a mapping of top-level packages to their distributions.

>>> import collections.abc
>>> pkgs = packages_distributions()
>>> all(isinstance(dist, collections.abc.Sequence) for dist in pkgs.values())
True
importlib_metadata.requires(distribution_name)

Return a list of requirements for the named package.

Returns

An iterator of requirements, suitable for packaging.requirement.Requirement.

importlib_metadata.version(distribution_name)

Get the version string for the named package.

Parameters

distribution_name – The name of the distribution package to query.

Returns

The version string for the package as defined in the package’s “Version” metadata key.