API Reference#

importlib_metadata module#

class importlib_metadata.Distribution(*args, **kwargs)#

Bases: DeprecatedNonAbstract

An abstract Python distribution package.

Custom providers may derive from this class and define the abstract methods to provide a concrete implementation for their environment.

static at(path: str | PathLike[str]) Distribution#

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(*, context: Context | None = None, **kwargs) Iterable[Distribution]#

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 packages matching the context.

property entry_points: EntryPoints#
property files: List[PackagePath] | None#

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 installed-files.txt or SOURCES.txt for egg-info) is missing. Result may be empty if the metadata exists but is empty.

classmethod from_name(name: str) Distribution#

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.

  • ValueError – When an invalid value is supplied for name.

abstract locate_file(path: str | PathLike[str]) SimplePath#

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

property metadata: 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: str#

Return the ‘Name’ metadata for the distribution package.

property origin#
abstract read_text(filename) str | None#

Attempt to load metadata file given by the name.

Python distribution metadata is organized by blobs of text typically represented as “files” in the metadata directory (e.g. package-1.0.dist-info). These files include things like:

  • METADATA: The distribution metadata including fields like Name and Version and Description.

  • entry_points.txt: A series of entry points defined by the Setuptools spec in an ini format with sections representing the groups.

  • RECORD: A record of files as installed by a typical installer.

A package may provide any set of files, including those not listed here or none at all.

Parameters:

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

Returns:

The text if found, otherwise None.

property requires: List[str] | None#

Generated requirements specified for this Distribution

property version: str#

Return the ‘Version’ metadata for the distribution package.

class importlib_metadata.DistributionFinder#

Bases: 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: List[str]#

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=Context()) Iterable[Distribution]#

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, **kwargs)#

Bases: Protocol

get(name: str, failobj: None = None) str | None#
get(name: str, failobj: _T) str | _T

Helper for @overload to raise when called.

get_all(name: str, failobj: None = None) List[Any] | None#
get_all(name: str, failobj: _T) List[Any] | _T

Helper for @overload to raise when called.

property json: Dict[str, str | List[str]]#

A JSON-compatible form of the metadata.

exception importlib_metadata.PackageNotFoundError#

Bases: ModuleNotFoundError

The package was not found.

property name: str#

module name

importlib_metadata.distribution(distribution_name: str) Distribution#

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) Iterable[Distribution]#

Get all Distribution instances in the current environment.

Returns:

An iterable of Distribution instances.

importlib_metadata.entry_points(**params) EntryPoints#

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()).

Returns:

EntryPoints for all installed packages.

importlib_metadata.files(distribution_name: str) List[PackagePath] | None#

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: str) 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: str) List[str] | None#

Return a list of requirements for the named package.

Returns:

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

importlib_metadata.version(distribution_name: str) str#

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.

class importlib_metadata._meta.PackageMetadata(*args, **kwargs)#

Bases: Protocol

get(name: str, failobj: None = None) str | None#
get(name: str, failobj: _T) str | _T

Helper for @overload to raise when called.

get_all(name: str, failobj: None = None) List[Any] | None#
get_all(name: str, failobj: _T) List[Any] | _T

Helper for @overload to raise when called.

property json: Dict[str, str | List[str]]#

A JSON-compatible form of the metadata.

class importlib_metadata._meta.SimplePath(*args, **kwargs)#

Bases: Protocol

A minimal subset of pathlib.Path required by Distribution.

exists() bool#
joinpath(other: str | PathLike[str]) SimplePath#
property parent: SimplePath#
read_bytes() bytes#
read_text(encoding=None) str#