importlib.metadata -- パッケージメタデータへのアクセス¶
バージョン 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.
重要
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.
By default, distribution metadata can live on the file system
or in zip archives on
sys.path. Through an extension mechanism, the metadata can live almost
anywhere.
参考
- https://importlib-metadata.readthedocs.io/
importlib_metadataのドキュメントはimportlib.metadataのバックポートです。これには、このモジュールのクラスと関数の APIリファレンス と、pkg_resourcesの既存のユーザーのための 移行ガイド があります。
概要¶
Let's say you wanted to get the version string for a
Distribution Package you've installed
using pip. We start by creating a virtual environment and installing
something into it:
$ 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'
You can also get a collection of entry points selectable by properties of the EntryPoint (typically 'group' or 'name'), such as
console_scripts, distutils.commands and others. Each group contains a
collection of EntryPoint objects.
ディストリビューションのメタデータ を取得することができます。:
>>> 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>
The group and name are arbitrary values defined by the package author
and usually a client will wish to resolve all entry points for a particular
group. Read the setuptools docs
for more information on entry points, their definition, and usage.
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オブジェクトを優先的に使用します。
Extending the search algorithm¶
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``.
"""
The DistributionFinder.Context object provides .path and .name
properties indicating the path to search and name to match and may
supply other relevant context.
What this means in practice is that to support finding distribution package
metadata in locations other than the file system, subclass
Distribution and implement the abstract methods. Then from
a custom finder, return instances of this derived Distribution in the
find_distributions() method.