Использование 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')
>>> wheel.module  
'wheel.cli'
>>> wheel.attr  
'main'
>>> wheel.extras  
[]
>>> 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

>>> util.locate()  
PosixPath('/home/gustav/example/lib/site-packages/wheel/util.py')

>>> 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. Вы должны использовать только методы и синтаксис словаря для доступа к содержимому метаданных.