importlib.metadata
– Accessing package 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/
The documentation for
importlib_metadata
, which supplies a backport ofimportlib.metadata
. This includes an API reference for this module’s classes and functions, as well as a migration guide for existing users ofpkg_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' 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: Опис
тепер включено в метадані, коли представлено через корисне навантаження. Символи продовження рядка видалено.
Додано атрибут 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¶
A convenience method to resolve the Distribution Package name (or names, in the case of a namespace package) that provide each importable top-level Python module or Import Package:
>>> packages_distributions()
{'importlib_metadata': ['importlib-metadata'], 'yaml': ['PyYAML'], 'jaraco': ['jaraco.classes', 'jaraco.functools'], ...}
Нове в версії 3.10.
Розподіл¶
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¶
By default, this package provides built-in support for discovery of metadata
for file system and zip file Distribution Packages.
This metadata finder search defaults to sys.path
, but varies slightly in how it interprets those values from how other import machinery does. In particular:
importlib.metadata
does not honorbytes
objects onsys.path
.importlib.metadata
will incidentally honorpathlib.Path
objects onsys.path
even though such values will be ignored for imports.
Розширення алгоритму пошуку¶
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. importlib.metadata
розширює цей протокол, шукаючи необов’язковий find_distributions
, викликаний у шукачах з sys.meta_path
, і представляє цей розширений інтерфейс як 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()
.