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の一部ではありません。 メタデータの内容にアクセスするには、辞書のようなメソッドと構文のみを使用する必要があります。