Использование importlib.metadata

Обзор

Предположим, вы хотите получить строку версии пакета, установленного с помощью pip. Мы начинаем с создания виртуальной среды и установки в неё чего-либо:

$ python3 -m venv example
$ source example/bin/activate
(example) $ pip install wheel

Вы можете получить строку версии для wheel, выполнив следующее:

(example) $ python
>>> from importlib.metadata import version  
>>> version('wheel')  
'0.32.3'

Вы также можете получить набор точек входа, сгруппированных по группам, например, console_scripts, distutils.commands и другие. Каждая группа содержит последовательность объектов EntryPoint.

Вы можете получить метаданные для дистрибутива:

>>> list(metadata('wheel'))  
['Metadata-Version', 'Name', 'Version', 'Summary', 'Home-page', 'Author', 'Author-email', 'Maintainer', 'Maintainer-email', 'License', 'Project-URL', 'Project-URL', 'Project-URL', 'Keywords', 'Platform', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Requires-Python', 'Provides-Extra', 'Requires-Dist', 'Requires-Dist']

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

Функциональный API

Этот пакет предоставляет следующую функциональность через свой публичный API.

>>> eps = entry_points()  
>>> list(eps)  
['console_scripts', 'distutils.commands', 'distutils.setup_keywords', 'egg_info.writers', 'setuptools.installation']
>>> scripts = eps['console_scripts']  
>>> wheel = [ep for ep in scripts if ep.name == 'wheel'][0]  
>>> wheel  
EntryPoint(name='wheel', value='wheel.cli:main', group='console_scripts')
>>> main = wheel.load()  
>>> main  
<function main at 0x103528488>

>>> wheel_metadata = metadata('wheel')  

>>> wheel_metadata['Requires-Python']  
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'

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

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

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

Дистрибутивы

Хотя приведенный выше API является наиболее распространённым и удобным в использовании, всю эту информацию можно получить из класса Distribution. Distribution — это абстрактный объект, представляющий метаданные пакета Python. Вы можете получить экземпляр Distribution:

>>> from importlib.metadata import distribution  
>>> dist = distribution('wheel')  

Таким образом, альтернативный способ получить номер версии — через экземпляр Distribution:

>>> dist.version  
'0.32.3'

На экземпляре Distribution доступны всевозможные дополнительные метаданные:

>>> dist.metadata['Requires-Python']  
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
>>> dist.metadata['License']  
'MIT'

Полный набор доступных метаданных здесь не описан. Дополнительные детали см. в PEP 566.

Расширение алгоритма поиска

Поскольку метаданные пакета недоступны через sys.path или непосредственно через загрузчики пакетов, метаданные пакета находятся с помощью поисковиков системы импорта. Чтобы найти метаданные пакета дистрибутива, importlib.metadata запрашивает список поисковиков метапути по sys.meta_path.

По умолчанию PathFinder для Python включает в себя обработку, которая вызывает importlib.metadata.MetadataPathFinder для поиска дистрибутивов, загруженных из типичных путей на основе файловой системы.

Абстрактный класс importlib.abc.MetaPathFinder определяет интерфейс, ожидаемый от поисковиков системой импорта Python. importlib.metadata расширяет этот протокол, ища необязательный вызов find_distributions в поисковиках из sys.meta_path и представляет этот расширенный интерфейс в виде абстрактного базового класса DistributionFinder, который определяет этот абстрактный метод:

@abc.abstractmethod
def find_distributions(context=DistributionFinder.Context()):
    """Return an iterable of all Distribution instances capable of
    loading the metadata for packages for the indicated ``context``.
    """

Объект DistributionFinder.Context предоставляет свойства .path и .name, указывающие на путь для поиска и имена для соответствия, и может предоставить другой контекст.

Это означает, что для поддержки поиска метаданных дистрибутивного пакета в местах, отличных от файловой системы, необходимо создать подкласс Distribution и реализовать абстрактные методы. Затем из пользовательского поисковика необходимо вернуть экземпляры этого производного класса Distribution в методе find_distributions().

Примечания

1

Технически, возвращаемый объект метаданных дистрибутива — экземпляр email.message.EmailMessage, но это деталь реализации, а не часть стабильного API. Для доступа к содержимому метаданных следует использовать только методы и синтаксис, подобные методам словаря.