importlib.metadata
-- パッケージメタデータへのアクセス¶
Added in version 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
は、Pythonの site-packages
ディレクトリに pip などのツールでインストールしたサードパーティの 配布パッケージ に対して動作します。具体的には、 dist-info
や egg-info
ディレクトリを持つ配布物や、 コアとなるメタデータの仕様 で定義されたメタデータを検出できるようにします。
重要
これらはPythonコード内でインポートできるトップレベルの パッケージ 名と 必ずしも 同等であったり、1:1 で対応するものではありません。1つの 配布パッケージ は複数の パッケージ (および単一のモジュール) を含むことができ、1つのトップレベルの パッケージ は、それが名前空間パッケージであれば複数の 配布パッケージ にマップすることができます。これらのマッピングを得るには packages_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']
また、 配布物のバージョン番号 を取得し、 構成ファイル をリストアップし、配布物の 配布物の要件 のリストを取得することができます。
- exception importlib.metadata.PackageNotFoundError¶
Subclass of
ModuleNotFoundError
raised by several functions in this module when queried for a distribution package which is not installed in the current Python environment.
機能 API¶
本パッケージは、公開APIを通じて以下の機能を提供します。
エントリポイント¶
- importlib.metadata.entry_points(**select_params)¶
Returns a
EntryPoints
instance describing entry points for the current environment. Any given keyword parameters are passed to theselect()
method for comparison to the attributes of the individual entry point definitions.Note: it is not currently possible to query for entry points based on their
EntryPoint.dist
attribute (as differentDistribution
instances do not currently compare equal, even if they have the same attributes)
- class importlib.metadata.EntryPoints¶
Details of a collection of installed entry points.
Also provides a
.groups
attribute that reports all identifed entry point groups, and a.names
attribute that reports all identified entry point names.
- class importlib.metadata.EntryPoint¶
Details of an installed entry point.
Each
EntryPoint
instance has.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, and.dist
for obtaining information regarding the distribution package that provides the entry point.
すべてのエントリポイントに問い合わせる:
>>> eps = entry_points()
The entry_points()
function returns a 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のドキュメント を参照してください。
バージョン 3.12 で変更: 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.
バージョン 3.13 で変更: EntryPoint
objects no longer present a tuple-like interface
(__getitem__()
).
配布物メタデータ¶
- importlib.metadata.metadata(distribution_name)¶
Return the distribution metadata corresponding to the named distribution package as a
PackageMetadata
instance.Raises
PackageNotFoundError
if the named distribution package is not installed in the current Python environment.
- class importlib.metadata.PackageMetadata¶
A concrete implementation of the PackageMetadata protocol.
In addition to providing the defined protocol methods and attributes, subscripting the instance is equivalent to calling the
get()
method.
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 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 full set of available metadata is not described here. See the PyPA Core metadata specification for additional details.
バージョン 3.10 で変更: ペイロードを通して提示されるとき、 Description
がメタデータに含まれるようになりました。行の継続文字は削除されました。
json
属性が追加されました。
配布物バージョン¶
- importlib.metadata.version(distribution_name)¶
Return the installed distribution package version for the named distribution package.
Raises
PackageNotFoundError
if the named distribution package is not installed in the current Python environment.
The version()
function is the quickest way to get a
Distribution Package's version
number, as a string:
>>> version('wheel')
'0.32.3'
配布物ファイル¶
- importlib.metadata.files(distribution_name)¶
Return the full set of files contained within the named distribution package.
Raises
PackageNotFoundError
if the named distribution package is not installed in the current Python environment.Returns
None
if the distribution is found but the installation database records reporting the files associated with the distribuion package are missing.
- class importlib.metadata.PackagePath¶
A
pathlib.PurePath
derived object with additionaldist
,size
, andhash
properties corresponding to the distribution package's installation metadata for that file.
The files()
function takes a
Distribution Package
name and returns all of the files installed by this distribution. Each file is reported
as a PackagePath
instance. 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 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.
配布物の要件¶
- importlib.metadata.requires(distribution_name)¶
Return the declared dependency specifiers for the named distribution package.
Raises
PackageNotFoundError
if the named distribution package is not installed in the current Python environment.
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¶
- importlib.metadata.packages_distributions()¶
Return a mapping from the top level module and import package names found via
sys.meta_path
to the names of the distribution packages (if any) that provide the corresponding files.To allow for namespace packages (which may have members provided by multiple distribution packages), each top level import name maps to a list of distribution names rather than mapping directly to a single name.
インポート可能なトップレベルの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¶
- importlib.metadata.distribution(distribution_name)¶
Return a
Distribution
instance describing the named distribution package.Raises
PackageNotFoundError
if the named distribution package is not installed in the current Python environment.
- class importlib.metadata.Distribution¶
Details of an installed distribution package.
Note: different
Distribution
instances do not currently compare equal, even if they relate to the same installed distribution and accordingly have the same attributes.
While the module level API described above is the most common and convenient usage,
you can get all of that information from the Distribution
class.
Distribution
is an abstract object that represents the metadata for
a Python Distribution Package.
You can get the concreate Distribution
subclass instance for an installed
distribution package by calling the distribution()
function:
>>> from importlib.metadata import distribution
>>> dist = distribution('wheel')
>>> type(dist)
<class 'importlib.metadata.PathDistribution'>
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 Distribution
instances:
>>> dist.metadata['Requires-Python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
>>> dist.metadata['License']
'MIT'
For editable packages, an origin
property may present PEP 610
metadata:
>>> dist.origin.url
'file:///path/to/wheel-0.32.3.editable-py3-none-any.whl'
The full set of available metadata is not described here. See the PyPA Core metadata specification for additional details.
Added in version 3.13: The .origin
property was added.
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
のインスタンスを返します。
使用例¶
Consider for example a custom finder that loads Python modules from a database:
class DatabaseImporter(importlib.abc.MetaPathFinder):
def __init__(self, db):
self.db = db
def find_spec(self, fullname, target=None) -> ModuleSpec:
return self.db.spec_from_name(fullname)
sys.meta_path.append(DatabaseImporter(connect_db(...)))
That importer now presumably provides importable modules from a
database, but it provides no metadata or entry points. For this
custom importer to provide metadata, it would also need to implement
DistributionFinder
:
from importlib.metadata import DistributionFinder
class DatabaseImporter(DistributionFinder):
...
def find_distributions(self, context=DistributionFinder.Context()):
query = dict(name=context.name) if context.name else {}
for dist_record in self.db.query_distributions(query):
yield DatabaseDistribution(dist_record)
In this way, query_distributions
would return records for
each distribution served by the database matching the query. For
example, if requests-1.0
is in the database, find_distributions
would yield a DatabaseDistribution
for Context(name='requests')
or Context(name=None)
.
For the sake of simplicity, this example ignores context.path
. The
path
attribute defaults to sys.path
and is the set of import paths to
be considered in the search. A DatabaseImporter
could potentially function
without any concern for a search path. Assuming the importer does no
partitioning, the "path" would be irrelevant. In order to illustrate the
purpose of path
, the example would need to illustrate a more complex
DatabaseImporter
whose behavior varied depending on
sys.path
/PYTHONPATH
. In that case, the find_distributions
should
honor the context.path
and only yield Distribution
s pertinent to that
path.
DatabaseDistribution
, then, would look something like:
class DatabaseDistribution(importlib.metadata.Distribution):
def __init__(self, record):
self.record = record
def read_text(self, filename):
"""
Read a file like "METADATA" for the current distribution.
"""
if filename == "METADATA":
return f"""Name: {self.record.name}
Version: {self.record.version}
"""
if filename == "entry_points.txt":
return "\n".join(
f"""[{ep.group}]\n{ep.name}={ep.value}"""
for ep in self.record.entry_points)
def locate_file(self, path):
raise RuntimeError("This distribution has no file system")
This basic implementation should provide metadata and entry points for
packages served by the DatabaseImporter
, assuming that the
record
supplies suitable .name
, .version
, and
.entry_points
attributes.
The DatabaseDistribution
may also provide other metadata files, like
RECORD
(required for Distribution.files
) or override the
implementation of Distribution.files
. See the source for more inspiration.