# `importlib.metadata` – Accessing package metadata

Нове в версії 3.8.

Змінено в версії 3.10: `importlib.metadata` більше не є тимчасовим.

Вихідний код: Lib/importlib/metadata/__init__.py

`importlib.metadata` is a library that provides access to the metadata of an installed Distribution Package, such as its entry points or its top-level names (Import Packages, modules, if any). Built in part on Python’s import system, this library intends to replace similar functionality in the entry point API and metadata API of `pkg_resources`. Along with `importlib.resources`, this package can eliminate the need to use the older and less efficient `pkg_resources` package.

`importlib.metadata` operates on third-party distribution packages installed into Python’s `site-packages` directory via tools such as pip. Specifically, it works with distributions with discoverable `dist-info` or `egg-info` directories, and metadata defined by the Core metadata specifications.

Важливо

These are not necessarily equivalent to or correspond 1:1 with the top-level import package names that can be imported inside Python code. One distribution package can contain multiple import packages (and single modules), and one top-level import package may map to multiple distribution packages if it is a namespace package. You can use package_distributions() to get a mapping between them.

By default, distribution metadata can live on the file system or in zip archives on `sys.path`. Through an extension mechanism, the metadata can live almost anywhere.

Дивись також

https://importlib-metadata.readthedocs.io/

  The documentation for `importlib_metadata`, which supplies a backport of `importlib.metadata`. This includes an API reference for this module’s classes and functions, as well as a migration guide for existing users of `pkg_resources`.

## Огляд

Let’s say you wanted to get the version string for a Distribution Package you’ve installed using `pip`. We start by creating a virtual environment and installing something into it:

    $ python -m venv example
    $ source example/bin/activate
    (example) $ python -m pip install wheel

Ви можете отримати рядок версії для `wheel`, виконавши наступне:

    (example) $ python
    >>> from importlib.metadata import version
    >>> version('wheel')
    '0.32.3'

You can also get a collection of entry points selectable by properties of the EntryPoint (typically „group“ or „name“), such as `console_scripts`, `distutils.commands` and others. Each group contains a collection of EntryPoint objects.

Ви можете отримати метадані для дистрибутива:

    >>> list(metadata('wheel'))
    ['Metadata-Version', 'Name', 'Version', 'Summary', 'Home-page', 'Author', 'Author-email', 'Maintainer', 'Maintainer-email', 'License', 'Project-URL', 'Project-URL', 'Project-URL', 'Keywords', 'Platform', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Requires-Python', 'Provides-Extra', 'Requires-Dist', 'Requires-Dist']

Ви також можете отримати номер версії дистрибутива, перелічити його складові файли та отримати список Вимоги до розповсюдження дистрибутива.

## Функціональний API

Цей пакет забезпечує такі функції через свій загальнодоступний API.

### Точки входу

The `entry_points()` function returns a collection of entry points. Entry points are represented by `EntryPoint` instances; each `EntryPoint` has a `.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.

Запитувати всі точки входу:

    >>> eps = entry_points()

The `entry_points()` function returns an `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')

Виберіть певний сценарій під назвою «колесо» (знаходиться в проекті колеса):

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

Аналогічно, запитайте цю точку входу під час вибору:

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

Огляньте вирішену точку входу:

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

Compatibility Note

The «selectable» entry points were introduced in `importlib_metadata` 3.6 and Python 3.10. Prior to those changes, `entry_points` accepted no parameters and always returned a dictionary of entry points, keyed by group. For compatibility, if no parameters are passed to entry_points, a `SelectableGroups` object is returned, implementing that dict interface. In the future, calling `entry_points` with no parameters will return an `EntryPoints` object. Users should rely on the selection interface to retrieve entry points by group.

### Метадані розповсюдження

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, a `PackageMetadata`, 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 actual type of the object returned by `metadata()` is an implementation detail and should be accessed only through the interface described by the PackageMetadata protocol.

Змінено в версії 3.10: `Опис` тепер включено в метадані, коли представлено через корисне навантаження. Символи продовження рядка видалено.

Додано атрибут `json`.

### Версії розповсюдження

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

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

### Файли розповсюдження

You can also get the full set of files contained within a distribution. The `files()` function takes a Distribution Package name and returns all of the files installed by this distribution. Each file object returned is a `PackagePath`, a `pathlib.PurePath` derived object with additional `dist`, `size`, and `hash` properties as indicated by the metadata. 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>

Отримавши файл, ви також можете прочитати його вміст:

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

### Вимоги до розповсюдження

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

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'], ...}

Нове в версії 3.10.

## Розподіл

While the above API is the most common and convenient usage, you can get all of that information from the `Distribution` class. A `Distribution` is an abstract object that represents the metadata for a Python Distribution Package. You can get the `Distribution` instance:

    >>> from importlib.metadata import distribution
    >>> dist = distribution('wheel')

Thus, an alternative way to get the version number is through the `Distribution` instance:

    >>> dist.version
    '0.32.3'

There are all kinds of additional metadata available on the `Distribution` instance:

    >>> dist.metadata['Requires-Python']
    '>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
    >>> dist.metadata['License']
    'MIT'

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

## Distribution Discovery

By default, this package provides built-in support for discovery of metadata for file system and zip file Distribution Packages. This metadata finder search defaults to `sys.path`, but varies slightly in how it interprets those values from how other import machinery does. In particular:

- `importlib.metadata` does not honor `bytes` objects on `sys.path`.

- `importlib.metadata` will incidentally honor `pathlib.Path` objects on `sys.path` even though such values will be ignored for imports.

## Розширення алгоритму пошуку

Because Distribution Package metadata is not available through `sys.path` searches, or package loaders directly, the metadata for a distribution is found through import system finders. To find a distribution package’s metadata, `importlib.metadata` queries the list of meta path finders on `sys.meta_path`.

By default `importlib.metadata` installs a finder for distribution packages found on the file system. This finder doesn’t actually find any distributions, but it can find their metadata.

Абстрактний клас `importlib.abc.MetaPathFinder` визначає інтерфейс, очікуваний від шукачів системою імпорту Python. `importlib.metadata` розширює цей протокол, шукаючи необов’язковий `find_distributions`, викликаний у шукачах з `sys.meta_path`, і представляє цей розширений інтерфейс як `DistributionFinder` абстрактний базовий клас, який визначає цей абстрактний метод:

    @abc.abstractmethod
    def find_distributions(context=DistributionFinder.Context()):
        """Return an iterable of all Distribution instances capable of
        loading the metadata for packages for the indicated ``context``.
        """

Об’єкт `DistributionFinder.Context` надає властивості `.path` і `.name`, що вказують шлях для пошуку та ім’я, яке відповідає, і може надати інший відповідний контекст.

На практиці це означає, що для підтримки пошуку метаданих пакетів дистрибутива в місцях, відмінних від файлової системи, створіть підклас `Distribution` і реалізуйте абстрактні методи. Потім із спеціального засобу пошуку поверніть екземпляри цього похідного `Distribution` у методі `find_distributions()`.