Entry points¶

importlib.metadata.entry_points(**select_params)¶

Returns a EntryPoints instance describing entry points for the current environment. Any given keyword parameters are passed to the select() method for comparison to the attributes of the individual entry point definitions.

Note: to query for entry points based on EntryPoint.dist attribute, use Distribution.entry_points() instead (as different Distribution instances do not currently compare equal, even if they have the same attributes)

class importlib.metadata.EntryPoints¶

Details of a collection of installed entry points.

Also provides a .groups attribute that reports all identified entry point groups, and a .names attribute that reports all identified entry point names.

class importlib.metadata.EntryPoint¶

Details of an installed entry point.

Each EntryPoint instance has .name, .group, and .value attributes and a .load() method to resolve the value. There are also .module, .attr, and .extras attributes for getting the components of the .value attribute, and .dist for obtaining information regarding the distribution package that provides the entry point.

Query all entry points:

>>> eps = entry_points()

The entry_points() function returns a EntryPoints object, a collection of all EntryPoint objects with names and groups attributes for convenience:

>>> sorted(eps.groups)
['console_scripts', 'distutils.commands', 'distutils.setup_keywords', 'egg_info.writers', 'setuptools.installation']

EntryPoints has a select() method to select entry points matching specific properties. Select entry points in the console_scripts group:

>>> scripts = eps.select(group='console_scripts')

Equivalently, since entry_points() passes keyword arguments through to select:

>>> scripts = entry_points(group='console_scripts')

Pick out a specific script named “wheel” (found in the wheel project):

>>> 'wheel' in scripts.names
True
>>> wheel = scripts['wheel']

Equivalently, query for that entry point during selection:

>>> (wheel,) = entry_points(group='console_scripts', name='wheel')
>>> (wheel,) = entry_points().select(group='console_scripts', name='wheel')

Inspect the resolved entry point:

>>> wheel
EntryPoint(name='wheel', value='wheel.cli:main', group='console_scripts')
>>> wheel.module
'wheel.cli'
>>> wheel.attr
'main'
>>> wheel.extras
[]
>>> main = wheel.load()
>>> main
<function main at 0x103528488>

The group and name are arbitrary values defined by the package author and usually a client will wish to resolve all entry points for a particular group. Read the setuptools docs for more information on entry points, their definition, and usage.

Distribution metadata¶

importlib.metadata.metadata(distribution_name)¶

Return the distribution metadata corresponding to the named distribution package as a PackageMetadata instance.

Raises PackageNotFoundError if the named distribution package is not installed in the current Python environment.

Raises MetadataNotFound if a distribution package is present but no METADATA file is present.

class importlib.metadata.PackageMetadata¶

A concrete implementation of the PackageMetadata protocol.

In addition to providing the defined protocol methods and attributes, subscripting the instance is equivalent to calling the get() method.

Every Distribution Package includes some metadata, which you can extract using the metadata() function:

>>> wheel_metadata = metadata('wheel')

The keys of the returned data structure name the metadata keywords, and the values are returned unparsed from the distribution metadata:

>>> wheel_metadata['Requires-Python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'

PackageMetadata also presents a json attribute that returns all the metadata in a JSON-compatible form per PEP 566:

>>> wheel_metadata.json['requires_python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'

The full set of available metadata is not described here. See the PyPA Core metadata specification for additional details.

Distribution versions¶

importlib.metadata.version(distribution_name)¶

Return the installed distribution package version for the named distribution package.

Raises PackageNotFoundError if the named distribution package is not installed in the current Python environment.

The version() function is the quickest way to get a Distribution Package’s version number, as a string:

>>> version('wheel')
'0.32.3'

Distribution files¶

importlib.metadata.files(distribution_name)¶

Return the full set of files contained within the named distribution package as PackagePath instances.

Raises PackageNotFoundError if the named distribution package is not installed in the current Python environment.

Returns None if the distribution is found but the installation database records reporting the files associated with the distribution package are missing.

class importlib.metadata.PackagePath¶

A pathlib.PurePath derived object with additional dist, size, and hash properties corresponding to the distribution package’s installation metadata for that file, also:

locate()¶

If possible, return the concrete SimplePath allowing to access data, or raise a NotImplementedError otherwise.

class importlib.metadata.SimplePath¶

A protocol representing a minimal subset of pathlib.Path that allows to check if it exists(), to traverse using joinpath() and parent, and to retrieve data using read_text() and read_bytes().

The files() function takes a Distribution Package name and returns all of the files installed by this distribution. For example:

>>> util = [p for p in files('wheel') if 'util.py' in str(p)][0]
>>> util
PackagePath('wheel/util.py')
>>> util.size
859
>>> util.dist
<importlib.metadata._hooks.PathDistribution object at 0x101e0cef0>
>>> util.hash
<FileHash mode: sha256 value: bYkw5oMccfazVCoYQwKkkemoVyMAFoR34mmKBx8R1NI>

Once you have the file, you can also read its contents:

>>> print(util.read_text())
import base64
import sys
...
def as_bytes(s):
    if isinstance(s, text_type):
        return s.encode('utf-8')
    return s

You can also use the locate() method to get the absolute path to the file:

>>> util.locate()
PosixPath('/home/gustav/example/lib/site-packages/wheel/util.py')

In the case where the metadata file listing files (RECORD or SOURCES.txt) is missing, files() will return None. The caller may wish to wrap calls to files() in always_iterable or otherwise guard against this condition if the target distribution is not known to have the metadata present.

Distribution requirements¶

importlib.metadata.requires(distribution_name)¶

Return the declared dependency specifiers for the named distribution package.

Raises PackageNotFoundError if the named distribution package is not installed in the current Python environment.

To get the full set of requirements for a Distribution Package, use the requires() function:

>>> requires('wheel')
["pytest (>=3.0.0) ; extra == 'test'", "pytest-cov ; extra == 'test'"]

Mapping import to distribution packages¶

importlib.metadata.packages_distributions()¶

Return a mapping from the top level module and import package names found via sys.meta_path to the names of the distribution packages (if any) that provide the corresponding files.

To allow for namespace packages (which may have members provided by multiple distribution packages), each top level import name maps to a list of distribution names rather than mapping directly to a single name.

A convenience method to resolve the Distribution Package name (or names, in the case of a namespace package) that provide each importable top-level Python module or Import Package:

>>> packages_distributions()
{'importlib_metadata': ['importlib-metadata'], 'yaml': ['PyYAML'], 'jaraco': ['jaraco.classes', 'jaraco.functools'], ...}

Some editable installs, do not supply top-level names, and thus this function is not reliable with such installs.

Example¶

Imagine a custom finder that loads Python modules from a database:

class DatabaseImporter(importlib.abc.MetaPathFinder):
    def __init__(self, db):
        self.db = db

    def find_spec(self, fullname, target=None) -> ModuleSpec:
        return self.db.spec_from_name(fullname)

sys.meta_path.append(DatabaseImporter(connect_db(...)))

That importer now presumably provides importable modules from a database, but it provides no metadata or entry points. For this custom importer to provide metadata, it would also need to implement DistributionFinder:

from importlib.metadata import DistributionFinder

class DatabaseImporter(DistributionFinder):
    ...

    def find_distributions(self, context=DistributionFinder.Context()):
        query = dict(name=context.name) if context.name else {}
        for dist_record in self.db.query_distributions(query):
            yield DatabaseDistribution(dist_record)

In this way, query_distributions would return records for each distribution served by the database matching the query. For example, if requests-1.0 is in the database, find_distributions would yield a DatabaseDistribution for Context(name='requests') or Context(name=None).

For the sake of simplicity, this example ignores context.path. The path attribute defaults to sys.path and is the set of import paths to be considered in the search. A DatabaseImporter could potentially function without any concern for a search path. Assuming the importer does no partitioning, the “path” would be irrelevant. In order to illustrate the purpose of path, the example would need to illustrate a more complex DatabaseImporter whose behavior varied depending on sys.path/PYTHONPATH. In that case, the find_distributions should honor the context.path and only yield Distributions pertinent to that path.

DatabaseDistribution, then, would look something like:

class DatabaseDistribution(importlib.metadata.Distribution):
    def __init__(self, record):
        self.record = record

    def read_text(self, filename):
        """
        Read a file like "METADATA" for the current distribution.
        """
        if filename == "METADATA":
            return f"""Name: {self.record.name}
Version: {self.record.version}
"""
        if filename == "entry_points.txt":
            return "\n".join(
              f"""[{ep.group}]\n{ep.name}={ep.value}"""
              for ep in self.record.entry_points)

    def locate_file(self, path):
        raise RuntimeError("This distribution has no file system")

This basic implementation should provide metadata and entry points for packages served by the DatabaseImporter, assuming that the record supplies suitable .name, .version, and .entry_points attributes.

The DatabaseDistribution may also provide other metadata files, like RECORD (required for Distribution.files) or override the implementation of Distribution.files. See the source for more inspiration.