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

Точки входа

importlib.metadata.entry_points(**select_params)

Возвращает экземпляр EntryPoints, описывающий точки входа для текущей среды. Все переданные именованные аргументы передаются методу select() для сравнения со значениями атрибутов отдельных определений точек входа.

Примечание: в настоящее время невозможно запрашивать точки входа по их атрибуту EntryPoint.dist (поскольку разные экземпляры Distribution сейчас не считаются равными, даже если у них одинаковые атрибуты).

class importlib.metadata.EntryPoints

Сведения о коллекции установленных точек входа.

Также предоставляет атрибут .groups, содержащий все обнаруженные группы точек входа, и атрибут .names, содержащий все обнаруженные имена точек входа.

class importlib.metadata.EntryPoint

Сведения об установленной точке входа.

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

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

>>> 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() передает именованные аргументы методу select:

>>> 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 не принимала параметров и всегда возвращала словарь точек входа с ключами-группами. Начиная с importlib_metadata 5.0 и Python 3.12, entry_points всегда возвращает объект EntryPoints. Варианты обеспечения совместимости см. в backports.entry_points_selectable.

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

importlib.metadata.metadata(distribution_name)

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

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

class importlib.metadata.PackageMetadata

Конкретная реализация протокола PackageMetadata.

Помимо предоставления определенных протоколом методов и атрибутов, обращение к элементу экземпляра эквивалентно вызову метода get().

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

>>> wheel_metadata = metadata('wheel')

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

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

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

Версии дистрибутивов

importlib.metadata.version(distribution_name)

Возвращает версию установленного пакета дистрибутива с указанным именем.

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

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

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

Файлы дистрибутива

importlib.metadata.files(distribution_name)

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

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

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

class importlib.metadata.PackagePath

Объект, производный от pathlib.PurePath, с дополнительными свойствами dist, size и hash, соответствующими метаданным установки пакета дистрибутива для этого файла.

Функция files() принимает имя пакета дистрибутива и возвращает все файлы, установленные этим дистрибутивом. Каждый файл представлен экземпляром PackagePath. Например:

>>> 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 или иным образом предусмотреть обработку этой ситуации.

Зависимости дистрибутива

importlib.metadata.requires(distribution_name)

Возвращает объявленные спецификаторы зависимостей для указанного пакета дистрибутива.

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

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

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

Соответствие пакетов импорта пакетам дистрибутивов

importlib.metadata.packages_distributions()

Возвращает соответствие между именами модулей и пакетов импорта верхнего уровня, обнаруженными через sys.meta_path, и именами пакетов дистрибутивов (если они есть), предоставляющих соответствующие файлы.

Для поддержки пакетов пространства имен (чьи элементы могут предоставляться несколькими пакетами дистрибутивов) каждому имени импорта верхнего уровня соответствует список имен дистрибутивов, а не одно имя.

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

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

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