API Reference¶

`importlib_metadata` module¶

APIs exposing metadata from third-party Python packages.

This codebase is shared between importlib.metadata in the stdlib and importlib_metadata in PyPI. See https://github.com/python/importlib_metadata/wiki/Development-Methodology for more detail.

class importlib_metadata.Distribution¶

Bases: object

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. Some providers may opt to override the default implementation of some properties to bypass the file-reading mechanism.

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¶

Return EntryPoints for this distribution.

Custom providers may provide the entry_points.txt file or override this property.

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.

Custom providers are recommended to provide a “RECORD” file (in read_text) or override this property to allow for callers to be able to resolve filenames provided by the package.

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.

abstractmethod locate_file(path: str | PathLike[str]) → SimplePath¶

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

This method is used by callers of Distribution.files() to locate files within the distribution. If it’s possible for a Distribution to represent files in the distribution as SimplePath objects, it should implement this method to resolve such objects.

Some Distribution providers may elect not to resolve SimplePath objects within the distribution by raising a NotImplementedError, but consumers of such a Distribution would be unable to invoke Distribution.files().

property metadata: PackageMetadata | None¶

Return the parsed metadata for this Distribution.

The returned object will have keys that name the various bits of metadata per the Core metadata specifications.

Custom providers may provide the METADATA file or override this property.

property name: str¶: Return the ‘Name’ metadata for the distribution package.

property origin¶

abstractmethod 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 as defined in the entry points spec.
RECORD: A record of files according to this recording spec.

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.

Custom providers should implement this interface in order to supply metadata.

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.

This mechanism gives a custom provider a means to solicit additional details from the caller beyond “name” and “path” when searching distributions. For example, imagine a provider that exposes suites of packages in either a “public” or “private” realm. A caller may wish to query only for distributions in a particular realm and could call distributions(realm="private") to signal to the custom provider to only include distributions from that realm.

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.

abstractmethod 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(**kwds)¶: Helper for @overload to raise when called.

get_all(**kwds)¶: 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

class importlib_metadata.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¶

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 | None¶

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¶

API Reference¶

importlib_metadata module¶

`importlib_metadata` module¶