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.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'], ...}

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

Пример

Представим пользовательский поисковый механизм, загружающий модули Python из базы данных:

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

Теперь этот импортёр, предположительно, предоставляет импортируемые модули из базы данных, но не предоставляет метаданные или точки входа. Чтобы этот пользовательский импортёр предоставлял метаданные, ему также потребуется реализовать DistributionFinder:

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)

Таким образом, query_distributions возвращал бы записи для каждого дистрибутива, предоставляемого базой данных и соответствующего запросу. Например, если в базе данных есть requests-1.0, find_distributions выдаст DatabaseDistribution для Context(name='requests') или Context(name=None).

Для простоты в этом примере не рассматривается context.path. По умолчанию атрибут path имеет значение sys.path и содержит пути импорта, которые следует учитывать при поиске. DatabaseImporter может работать и без учёта пути поиска. Если импортёр не выполняет разбиение на разделы, «путь» не имеет значения. Чтобы показать назначение path, пример должен был бы иллюстрировать более сложный DatabaseImporter, поведение которого меняется в зависимости от sys.path/PYTHONPATH. В этом случае find_distributions должен учитывать context.path и выдавать только Distribution, относящиеся к этому пути.

Тогда DatabaseDistribution выглядел бы примерно так:

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

    def read_text(self, filename):
        """
        Read a file like "METADATA" for the current 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")

Эта простая реализация должна предоставлять метаданные и точки входа для пакетов, обслуживаемых DatabaseImporter, при условии, что record предоставляет подходящие атрибуты .name, .version и .entry_points.

DatabaseDistribution также может предоставлять другие файлы метаданных, например RECORD (необходимый для Distribution.files), или переопределять реализацию Distribution.files. Дополнительные идеи можно почерпнуть из исходного кода.