# `importlib.metadata` -- Accessing package metadata

Added in version 3.8.

バージョン 3.10 で変更: `importlib.metadata` は、暫定的なものではなくなりました。

ソースコード: Lib/importlib/metadata/__init__.py

`importlib.metadata` is a library that provides access to the metadata of an installed Distribution Package, such as its entry points or its top-level names (Import Packages, modules, if any). Built in part on Python's import system, this library intends to replace similar functionality in the entry point API and metadata API of `pkg_resources`. Along with `importlib.resources`, this package can eliminate the need to use the older and less efficient `pkg_resources` package.

`importlib.metadata` operates on third-party distribution packages installed into Python's `site-packages` directory via tools such as pip. Specifically, it works with distributions with discoverable `dist-info` or `egg-info` directories, and metadata defined by the Core metadata specifications.

重要

これらはPythonコード内でインポートできるトップレベルの パッケージ 名と 必ずしも 同等であったり、1:1 で対応するものではありません。1つの 配布パッケージ は複数の パッケージ (および単一のモジュール) を含むことができ、1つのトップレベルの パッケージ は、それが名前空間パッケージであれば複数の 配布パッケージ にマップすることができます。これらのマッピングを得るには package_distributions() を使用します。

デフォルトでは、配布物のメタデータはファイルシステム上、または `sys.path` のzipアーカイブに保存されます。拡張機構により、メタデータはほとんどどこにでも置くことができます。

参考

https://importlib-metadata.readthedocs.io/

  `importlib_metadata` のドキュメントは `importlib.metadata` のバックポートです。これには、このモジュールのクラスと関数の APIリファレンス と、 `pkg_resources` の既存のユーザーのための 移行ガイド があります。

## 概要

例えば、`pip` を使ってインストールした 配布パッケージ のバージョン文字列を取得したいとします。 まず、仮想環境を作成し、そこに何かをインストールすることから始めましょう:

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

以下のように実行することで、`wheel` のバージョン文字列を取得することができます:

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

また、 `console_scripts` や `distutils.commands` などのエントリポイントのプロパティ(通常は 'group' や 'name' )で選択可能なエントリポイントの集合を取得することができます。 各グループは エントリポイント オブジェクトの集合を含んでいます。

ディストリビューションのメタデータ を取得することができます。:

    >>> 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` は `.name`, `.group`, `.value` 属性と値を解決する `.load()` メソッドを持っています。 また、 `.value` 属性の構成要素を取得するための `.module`, `.attr`, `.extras` 属性が存在します。

すべてのエントリポイントに問い合わせる:

    >>> eps = entry_points()

`entry_points()` 関数は、すべての `EntryPoint` オブジェクトを集めた `EntryPoints` オブジェクトを、便宜上 `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')

Equivalently, since `entry_points` passes keyword arguments through to select:

    >>> 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のドキュメント を参照してください。

互換性に関する注意

The "selectable" entry points were introduced in `importlib_metadata` 3.6 and Python 3.10. Prior to those changes, `entry_points` accepted no parameters and always returned a dictionary of entry points, keyed by group. With `importlib_metadata` 5.0 and Python 3.12, `entry_points` always returns an `EntryPoints` object. See backports.entry_points_selectable for compatibility options.

### 配布物メタデータ

すべての 配布パッケージ にはメタデータが含まれており、 `metadata()` 関数を使って取得することができます:

    >>> wheel_metadata = metadata('wheel')

返されたデータ構造である `PackageMetadata` のキーはメタデータのキーワードを表し、値は配布パッケージのメタデータから解析されずに返されます:

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

`PackageMetadata` には `json` 属性があり、 PEP 566 に従ってすべてのメタデータをJSON互換の形式で返します:

    >>> wheel_metadata.json['requires_python']
    '>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'

注釈

`metadata()` が返すオブジェクトの実際の型は実装の詳細であり、 PackageMetadataプロトコル が示すインターフェースを通じてのみアクセスすることができます。

バージョン 3.10 で変更: ペイロードを通して提示されるとき、 `Description` がメタデータに含まれるようになりました。行の継続文字は削除されました。

`json` 属性が追加されました。

### 配布物バージョン

`version()` 関数は 配布パッケージ のバージョン番号を文字列で取得するもっとも簡単な方法です。:

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

### 配布物ファイル

また、配布パッケージに含まれるファイルのフルセットを取得することもできます。`files()` 関数は 配布パッケージ 名を受け取り、この配布パッケージにインストールされているすべてのファイルを返します。返される各ファイルオブジェクトは `PackagePath` で、 `pathlib.PurePath` から派生したオブジェクトに、メタデータで示された `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

また、 `locate` メソッドを使用すると、ファイルへの絶対パスを取得することができます:

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

In the case where the metadata file listing files (RECORD or SOURCES.txt) is missing, `files()` will return `None`. The caller may wish to wrap calls to `files()` in always_iterable or otherwise guard against this condition if the target distribution is not known to have the metadata present.

### 配布物の要件

配布パッケージ に必要なすべての要件を取得するには、 `requires()` 関数を使用します:

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

### Mapping import to distribution packages

インポート可能なトップレベルのPythonモジュールまたは パッケージ を提供する 配布パッケージ 名(名前空間パッケージの場合はその名前)を解決する便利なメソッドです:

    >>> packages_distributions()
    {'importlib_metadata': ['importlib-metadata'], 'yaml': ['PyYAML'], 'jaraco': ['jaraco.classes', 'jaraco.functools'], ...}

Some editable installs, do not supply top-level names, and thus this function is not reliable with such installs.

Added in version 3.10.

## Distributions

上記の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'

利用可能なメタデータのフルセットは、ここでは説明しません。詳細は コアとなるメタデータの仕様 を参照してください。

## Distribution Discovery

デフォルトでは、このパッケージは組み込みで、ファイルシステムおよび zip ファイル 配布パッケージ のメタデータを発見するためのサポートを提供します。このメタデータ検索のデフォルトは `sys.path` ですが、その値をどのように解釈するかは、他のインポート機構が行う方法とは若干異なります。具体的には:

- `importlib.metadata` は `sys.path` の `bytes` オブジェクトを受け入れません。

- `importlib.metadata` は、インポート時には無視されますが、 `sys.path` 上の `pathlib.Path` オブジェクトを優先的に使用します。

## 検索アルゴリズムの拡張

Because Distribution Package metadata is not available through `sys.path` searches, or package loaders directly, the metadata for a distribution is found through import system finders. To find a distribution package's metadata, `importlib.metadata` queries the list of meta path finders on `sys.meta_path`.

By default `importlib.metadata` installs a finder for distribution packages found on the file system. This finder doesn't actually find any distributions, but it can find their metadata.

抽象クラス `importlib.abc.MetaPathFinder` はPythonの importシステムによってファインダーに期待されるインターフェイスを定義しています。 `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` をサブクラス化して抽象メソッドを実装します。そして、カスタムファインダーから `find_distributions()` メソッドで、派生した `Distribution` のインスタンスを返します。