Использование 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.

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

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

Метаданные дистрибутива

Каждый дистрибутив содержит определённые метаданные, которые можно извлечь с помощью функции 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'], ...}