importlib.metadata – Доступ к метаданным пакета¶importlib.metadata – Accessing package metadata

Обзор¶Overview

Предположим, вы хотите получить строку версии для дистрибутивного пакета, установленного с помощью pip. Начнём с создания виртуального окружения и установки чего-нибудь в него:

$ 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'

Вы также можете получить коллекцию точек входа, выбираемых по свойствам EntryPoint (обычно 'group' или 'name'), например console_scripts, distutils.commands и другие. Каждая группа содержит коллекцию объектов EntryPoint.

Вы можете получить метаданные для дистрибутива:

>>> 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']

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

exception importlib.metadata.PackageNotFoundError¶

Подкласс ModuleNotFoundError, вызываемый несколькими функциями в этом модуле при запросе дистрибутивного пакета, который не установлен в текущем окружении Python.

exception importlib.metadata.MetadataNotFound¶

Подкласс FileNotFoundError, возбуждаемый при попытке загрузить метаданные из папки дистрибутива, которая пуста или не содержит файла метаданных.

Функциональное API¶Functional API

Этот пакет предоставляет следующие функции через свой публичный API.

>>> eps = entry_points()

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

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

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

>>> wheel_metadata = metadata('wheel')

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

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

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

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

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

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

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

Дистрибутивы¶Distributions

Хотя описанный выше API уровня модуля является наиболее распространённым и удобным, вся эта информация доступна из класса Distribution. Distribution – это абстрактный объект, представляющий метаданные для дистрибутивного пакета Python. Получить конкретный экземпляр подкласса Distribution для установленного дистрибутивного пакета можно, вызвав функцию distribution():

>>> from importlib.metadata import distribution
>>> dist = distribution('wheel')
>>> type(dist)
<class 'importlib.metadata.PathDistribution'>

importlib.metadata.distribution(distribution_name)¶

Возвращает экземпляр Distribution, описывающий именованный дистрибутивный пакет.

Вызывает PackageNotFoundError, если именованный дистрибутивный пакет не установлен в текущем окружении Python.

Таким образом, альтернативный способ получить, например, номер версии – через атрибут Distribution.version:

>>> dist.version
'0.32.3'

То же самое относится к entry_points() и files().

class importlib.metadata.Distribution¶

Сведения об установленном дистрибутивном пакете.

Примечание: разные экземпляры Distribution в настоящее время не считаются равными, даже если они относятся к одному и тому же установленному дистрибутиву и, соответственно, имеют одинаковые атрибуты.

static at(path)¶

classmethod from_name(name)¶

Возвращает экземпляр Distribution по указанному пути или с указанным именем.

classmethod discover(*, context=None, **kwargs)¶

Возвращает итерируемый объект с экземплярами Distribution для всех пакетов (см. distribution-discovery).

Необязательный аргумент context – это экземпляр DistributionFinder.Context, используемый для изменения поиска дистрибутивов. Альтернативно, kwargs может содержать именованные аргументы для создания нового DistributionFinder.Context.

metadata: PackageMetadata¶

Вызывает MetadataNotFound, если файл METADATA отсутствует в дистрибутиве.

На экземплярах Distribution доступны разнообразные дополнительные метаданные в виде экземпляра PackageMetadata:

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

Полный набор доступных метаданных здесь не описывается. За дополнительными сведениями обратитесь к спецификации основных метаданных PyPA.

name: str¶

requires: list[str]¶

version: str¶

Некоторые поля метаданных также доступны как сокращённые свойства.

Добавлено в версии 3.10: Было добавлено сокращённое свойство name.

origin¶

Для редактируемых пакетов свойство origin может содержать метаданные PEP 610 (для нередактируемых пакетов origin равно None):

>>> dist.origin.url
'file:///path/to/wheel-0.32.3.editable-py3-none-any.whl'

Объект origin соответствует структуре данных прямого URL.

Добавлено в версии 3.13.

entry_points: EntryPoints¶

Точки входа, предоставляемые этим пакетом дистрибутива.

files: list[PackagePath] | None¶

Все файлы, содержащиеся в этом пакете дистрибутива. Как и files(), возвращает None, если записи отсутствуют.

Следующие два абстрактных метода необходимо реализовать при реализации пользовательских провайдеров:

locate_file(path)¶

Как и PackagePath.locate(), возвращает SimplePath для указанного пути. Принимает os.PathLike или str.

read_text(filename)¶

Сокращённая запись для distribution.locate_file(filename).read_text().

Обнаружение дистрибутивов¶Distribution Discovery

По умолчанию этот пакет предоставляет встроенную поддержку поиска метаданных для дистрибутивных пакетов файловой системы и zip-файлов. Поиск метаданных по умолчанию использует sys.path, но трактует эти значения немного иначе, чем другие механизмы импорта. В частности:

• importlib.metadata не учитывает объекты bytes из sys.path.

• importlib.metadata случайно будет учитывать объекты pathlib.Path из sys.path, хотя такие значения игнорируются при импорте.

class importlib.metadata.DistributionFinder¶

Подкласс MetaPathFinder, способный обнаруживать установленные дистрибутивы.

Пользовательские провайдеры должны реализовать этот интерфейс для предоставления метаданных.

class Context(**kwargs)¶

Context даёт пользовательскому провайдеру возможность запрашивать дополнительные сведения у вызывающих сторон функций поиска дистрибутивов, таких как distributions() или Distribution.discover(), помимо .name и .path при поиске дистрибутивов.

Например, провайдер может предоставлять наборы пакетов в «публичном» или «частном» realm. Вызывающая сторона функций поиска дистрибутивов может захотеть запросить только дистрибутивы в определённой области и может вызвать distributions(realm="private"), чтобы указать пользовательскому провайдеру включать только дистрибутивы из этой области.

Каждый DistributionFinder должен принимать любые параметры и по возможности стараться соблюдать канонические параметры, определённые ниже.

См. раздел Реализация пользовательских провайдеров для получения дополнительных сведений.

name¶

Конкретное имя, которому должен соответствовать искатель дистрибутивов.

.name со значением None соответствует всем дистрибутивам.

path¶

Свойство, предоставляющее последовательность путей к каталогам, которые должен просматривать поисковик дистрибутивов.

Обычно относится к путям установленных пакетов Python, например, к каталогам site-packages, и по умолчанию равно sys.path.

importlib.metadata.distributions(**kwargs)¶

Возвращает итерируемый объект с экземплярами Distribution для всех пакетов.

Аргумент kwargs может содержать именованный аргумент context, экземпляр DistributionFinder.Context или ключевые аргументы для создания нового DistributionFinder.Context. DistributionFinder.Context используется для изменения поиска дистрибутивов.

Реализация пользовательских провайдеров¶Implementing Custom Providers

importlib.metadata охватывает два API: один для потребителей, а другой для провайдеров. Большинство пользователей являются потребителями, потребляя метаданные, предоставляемые пакетами. Однако есть и другие сценарии, в которых пользователи хотят предоставлять метаданные через какой-то другой механизм, например, вместе с пользовательским импортёром. Такой сценарий требует пользовательского провайдера.

Поскольку метаданные дистрибутивного пакета недоступны напрямую через поиск sys.path или загрузчики пакетов, метаданные для дистрибутива находятся через искатели системы импорта. Чтобы найти метаданные дистрибутивного пакета, importlib.metadata опрашивает список искателей путей метаданных из sys.meta_path.

Реализация включает хуки, встроенные в PathFinder, которые предоставляют метаданные для дистрибутивных пакетов, найденных в файловой системе.

Абстрактный класс importlib.abc.MetaPathFinder определяет интерфейс, ожидаемый от искателей системой импорта Python. importlib.metadata расширяет этот протокол, проверяя наличие опционального вызываемого объекта find_distributions у искателей из sys.meta_path, и предоставляет этот расширенный интерфейс как абстрактный базовый класс DistributionFinder, который определяет следующий абстрактный метод:

@abc.abstractmethod
def find_distributions(context=DistributionFinder.Context()) -> Iterable[Distribution]:
    """Возвращает итерируемый объект со всеми экземплярами Distribution, способными
    загружать метаданные для пакетов для указанного ``context``.
    """

Объект DistributionFinder.Context предоставляет свойства path и name, указывающие путь для поиска и имя для сопоставления, а также может предоставлять другой соответствующий контекст, запрашиваемый потребителем.

На практике, чтобы поддерживать поиск метаданных дистрибутивных пакетов в местах, отличных от файловой системы, создайте подкласс Distribution и реализуйте абстрактные методы. Затем из пользовательского искателя возвращайте экземпляры этого производного Distribution в методе find_distributions().

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

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)

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

    def read_text(self, filename):
        """
        Читает файл, например "METADATA", для текущего 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")