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() передаёт ключевые аргументы для выбора:

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

Помимо предоставления определённых методов и атрибутов протокола, обращение к экземпляру по индексу эквивалентно вызову метода 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 Core metadata specification для получения дополнительной информации.

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

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. Смотрите исходный код для вдохновения.