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 являются произвольными значениями, определенными автором пакета, и обычно клиент желает разрешить все точки входа для определенной группы. Прочитайте the setuptools docs для получения дополнительной информации о точках входа, их определении и использовании.

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

«Выбираемые» точки входа были введены в importlib_metadata 3.6 и Python 3.10. До этих изменений entry_points не принимал никаких параметров и всегда возвращал словарь точек входа, заданный по группам. Для обеспечения совместимости, если в entry_points не передаются параметры, возвращается объект SelectableGroups, реализующий этот интерфейс dict. В будущем при вызове entry_points без параметров будет возвращен объект EntryPoints. Пользователи должны полагаться на интерфейс выбора для поиска точек входа по группам.

Метаданные распространения¶

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

>>> wheel_metadata = metadata('wheel')  

Ключи возвращаемой структуры данных, a 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() - это самый быстрый способ получить номер версии Distribution Package в виде строки:

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

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

Вы также можете получить полный набор файлов, содержащихся в дистрибутиве. Функция files() принимает имя Distribution Package и возвращает все файлы, установленные в этом дистрибутиве. Каждый возвращаемый файловый объект является 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')

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

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

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

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

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

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

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