importlib.metadata -- パッケージメタデータへのアクセス¶
バージョン 3.8 で追加.
バージョン 3.10 で変更: importlib.metadata は暫定的なものではなくなりました。
ソースコード: Lib/importlib/metadata/__init__.py
importlib.metadata はインストールされた 配布パッケージ のエントリポイントやトップレベル名 (あれば、 パッケージ やモジュール) のようなメタデータへのアクセスを提供するライブラリです。Pythonのインポートシステムをベースに構築されており、このライブラリは pkg_resources の entry point API と metadata API にある同様の機能を置き換えることを目的としています。importlib.resources と共に、このパッケージは古くて効率の悪い pkg_resources パッケージを使う必要性を無くすことができます。
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.
重要
These are not necessarily equivalent to or correspond 1:1 with the top-level import package names that can be imported inside Python code. One distribution package can contain multiple import packages (and single modules), and one top-level import package may map to multiple distribution packages if it is a namespace package. You can use package_distributions() to get a mapping between them.
デフォルトでは、配布物のメタデータはファイルシステム上、または 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を通じて以下の機能を提供します。
エントリポイント¶
The entry_points() function returns a collection of entry points.
Entry points are represented by EntryPoint instances;
each EntryPoint has a .name, .group, and .value attributes and
a .load() method to resolve the value. There are also .module,
.attr, and .extras attributes for getting the components of the
.value attribute.
すべてのエントリポイントに問い合わせる:
>>> eps = entry_points()
The entry_points() function returns an EntryPoints object,
a collection of all EntryPoint objects with names and groups
attributes for convenience:
>>> sorted(eps.groups)
['console_scripts', 'distutils.commands', 'distutils.setup_keywords', 'egg_info.writers', 'setuptools.installation']
EntryPoints has a select method to select entry points
matching specific properties. Select entry points in the
console_scripts group:
>>> 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のドキュメント を参照してください。
Compatibility Note
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. For compatibility, if no parameters are passed to entry_points,
a SelectableGroups object is returned, implementing that dict
interface. In the future, calling entry_points with no parameters
will return an EntryPoints object. Users should rely on the selection
interface to retrieve entry points by group.
配布物メタデータ¶
Every Distribution Package includes some metadata,
which you can extract using the
metadata() function:
>>> wheel_metadata = metadata('wheel')
The keys of the returned data structure, a PackageMetadata,
name the metadata keywords, and
the values are returned unparsed from the distribution metadata:
>>> wheel_metadata['Requires-Python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
PackageMetadata also presents a json attribute that returns
all the metadata in a JSON-compatible form per PEP 566:
>>> wheel_metadata.json['requires_python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
注釈
The actual type of the object returned by metadata() is an
implementation detail and should be accessed only through the interface
described by the
PackageMetadata protocol.
バージョン 3.10 で変更: ペイロードを通して提示されるとき、 Description がメタデータに含まれるようになりました。行の継続文字は削除されました。
json 属性が追加されました。
配布物バージョン¶
The version() function is the quickest way to get a
Distribution Package's version
number, as a string:
>>> version('wheel')
'0.32.3'
配布物ファイル¶
You can also get the full set of files contained within a distribution. The
files() function takes a Distribution Package name
and returns all of the
files installed by this distribution. Each file object returned is a
PackagePath, a pathlib.PurePath derived object with additional dist,
size, and hash properties as indicated by the metadata. For example:
>>> 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
You can also use the locate method to get a the absolute path to the
file:
>>> 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.
配布物の要件¶
To get the full set of requirements for a Distribution Package,
use the requires()
function:
>>> 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'], ...}
バージョン 3.10 で追加.
Distributions¶
While the above API is the most common and convenient usage, you can get all
of that information from the Distribution class. A Distribution is an
abstract object that represents the metadata for
a Python Distribution Package. You can
get the Distribution instance:
>>> from importlib.metadata import distribution
>>> dist = distribution('wheel')
Thus, an alternative way to get the version number is through the
Distribution instance:
>>> dist.version
'0.32.3'
There are all kinds of additional metadata available on the Distribution
instance:
>>> dist.metadata['Requires-Python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
>>> dist.metadata['License']
'MIT'
The full set of available metadata is not described here. See the Core metadata specifications for additional details.
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 のインスタンスを返します。