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

Точки входа

Функция entry_points() возвращает коллекцию точек входа. Точки входа представлены экземплярами EntryPoint; каждый экземпляр EntryPoint имеет атрибуты .name, .group и .value, а также метод .load() для разрешения значения. Также есть атрибуты .module, .attr и .extras для получения компонентов атрибута .value.

Запрос всех точек входа:

>>> eps = entry_points()  

Функция entry_points() возвращает объект EntryPoints, коллекцию всех объектов EntryPoint с атрибутами names и groups для удобства:

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

EntryPoints имеет метод select для выбора точек входа, соответствующих определённым свойствам. Выбор точек входа в группе console_scripts:

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

Аналогично, так как entry_points передает ключевые аргументы для выбора:

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

Выбор конкретного скрипта с именем «wheel» (найденного в проекте wheel):

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

group и name — произвольные значения, определённые автором пакета, и обычно клиент захочет разрешить все точки входа для определённой группы. Подробнее о точках входа, их определении и использовании см. документацию setuptools.

Примечание по совместимости

Точки входа «selectable» были добавлены в importlib_metadata 3.6 и Python 3.10. До этих изменений entry_points не принимал параметров и всегда возвращал словарь точек входа, индексированных по группам. С importlib_metadata 5.0 и Python 3.12, entry_points всегда возвращает объект EntryPoints. См. backports.entry_points_selectable для вариантов совместимости.

Данные о распространении

Каждый пакет распространения включает некоторые метаданные, которые можно извлечь с помощью функции metadata():

>>> wheel_metadata = metadata('wheel')  

Ключи возвращаемой структуры данных, PackageMetadata, представляют метаданные, а значения возвращаются необработанными из метаданных пакета распространения:

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

PackageMetadata также предоставляет атрибут json, который возвращает все метаданные в формате, совместимом с JSON, в соответствии с PEP 566:

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

Версии распространения

Функция version() — самый быстрый способ получить номер версии пакета распространения в виде строки:

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

Файлы распространения

Вы также можете получить полный набор файлов, содержащихся в пакете распространения. Функция files() принимает имя пакета распространения и возвращает все файлы, установленные этим пакетом. Каждый возвращаемый объект файла является объектом PackagePath, производным объектом pathlib.PurePath с дополнительными свойствами dist, size и hash, как указано в метаданных. Например:

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

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

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

В случае отсутствия файла метаданных, перечисляющего файлы (RECORD или SOURCES.txt), files() вернёт None. Вызывающий код может обернуть вызовы files() в always_iterable или каким-либо другим способом защититься от этого условия, если известно, что у целевого пакета распространения отсутствуют метаданные.

Требования к распространению

Чтобы получить полный набор требований к пакету распространения, используйте функцию requires():

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

Сопоставление импорта с пакетами распространения

Удобный метод для разрешения имени пакета распространения (или имён в случае пакетного пространства имён), которые предоставляют каждый импортируемый верхнеуровневый Python-модуль или пакет импорта:

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

Некоторые изменяемые установки не предоставляют верхнеуровневые имена, поэтому эта функция не надёжна с такими установками.