importlib.metadataを使用する

バージョン3.8の新機能。

ソースコード： ：source： `Lib / importlib / metadata.py`

ノート

この機能は暫定的なものであり、標準ライブラリの通常のバージョンセマンティクスから逸脱する可能性があります。

importlib.metadataは、インストールされたパッケージメタデータへのアクセスを提供するライブラリです。 Pythonのインポートシステムに一部組み込まれているこのライブラリは、pkg_resourcesのエントリポイントAPI およびメタデータAPI の同様の機能を置き換えることを目的としています。 Python3.7以降の importlib.resources （古いバージョンのPythonでは importlib_resources としてバックポートされます）とともに、これにより、古くて効率の悪いpkg_resourcesを使用する必要がなくなります。 ] パッケージ。

「インストール済みパッケージ」とは、通常、 pip などのツールを介してPythonのsite-packagesディレクトリにインストールされるサードパーティパッケージを意味します。具体的には、検出可能なdist-infoまたはegg-infoディレクトリと、 PEP 566 またはその古い仕様で定義されたメタデータを持つパッケージを意味します。デフォルトでは、パッケージメタデータはファイルシステムまたは sys.path のzipアーカイブに存在できます。拡張メカニズムにより、メタデータはほぼどこにでも存在できます。

概要

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を介して次の機能を提供します。

エントリポイント

entry_points()関数は、グループごとにキー設定されたすべてのエントリポイントの辞書を返します。エントリポイントはEntryPointインスタンスで表されます。各EntryPointには、.name、.group、および.value属性と、値を解決するための.load()メソッドがあります。

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

groupおよびnameはパッケージの作成者によって定義された任意の値であり、通常、クライアントは特定のグループのすべてのエントリポイントを解決したいと考えています。エントリポイント、その定義、および使用法の詳細については、 setuptools docs をお読みください。

配布メタデータ

すべてのディストリビューションには、metadata()関数を使用して抽出できるメタデータが含まれています。

>>> wheel_metadata = metadata('wheel')

返されるデータ構造 1 のキーは、メタデータキーワードに名前を付け、それらの値は、配布メタデータから解析されずに返されます。

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

配布バージョン

version()関数は、ディストリビューションのバージョン番号を文字列として取得する最も簡単な方法です。

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

配布ファイル

ディストリビューションに含まれるファイルのフルセットを取得することもできます。 files()関数は、ディストリビューションパッケージ名を受け取り、このディストリビューションによってインストールされたすべてのファイルを返します。返される各ファイルオブジェクトは、PackagePath、 pathlib.Path 派生オブジェクトであり、dist、size、およびhashプロパティが追加されています。メタデータによって示されます。例えば：

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

メタデータファイル一覧ファイル（RECORDまたはSOURCES.txt）がない場合、files()はNoneを返します。呼び出し元は、files()への呼び出しを always_iterable でラップするか、ターゲットディストリビューションにメタデータが存在することがわかっていない場合にこの状態を防ぐことができます。

配布要件

ディストリビューションの要件の完全なセットを取得するには、requires()関数を使用します。

>>> 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 上のメタパスファインダーのリストを照会します。

PythonのデフォルトのPathFinderには、一般的なファイルシステムベースのパスからロードされたディストリビューションを検索するためにimportlib.metadata.MetadataPathFinderを呼び出すフックが含まれています。

抽象クラス importlib.abc.MetaPathFinder は、Pythonのインポートシステムがファインダーに期待するインターフェースを定義します。 importlib.metadataは、 sys.meta_path のファインダーで呼び出し可能なオプションのfind_distributionsを探すことでこのプロトコルを拡張し、この拡張インターフェイスを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の一部ではありません。メタデータの内容にアクセスするには、辞書のようなメソッドと構文のみを使用する必要があります。

importlib.metadataの使用—Pythonドキュメント