`importlib.metadata` -- دسترسی به فراداده‌ی بسته¶

اضافه شده در نسخه‌ی 3.8.

تغییر یافته در نسخه‌ی 3.10: importlib.metadata دیگر موقتی نیست.

کد منبع: Lib/importlib/metadata/__init__.py

importlib.metadata کتابخانه‌ای است که دسترسی به فراداده‌ی یک بسته توزیعی نصب‌شده را فراهم می‌کند، مانند نقاط ورود آن یا نام‌های سطح بالای آن (بسته‌های ایمپورت، ماژول‌ها، در صورت وجود). این کتابخانه که تا حدی بر پایه‌ی سیستم ایمپورت پایتون ساخته شده است، APIهای نقطه‌ی ورود و فراداده را فراهم می‌کند که پیش‌تر توسط بسته‌ی اکنون حذف‌شده‌ی pkg_resources ارائه می‌شدند. این کتابخانه به همراه importlib.resources، جایگزین pkg_resources شده است.

importlib.metadata روی بسته‌های توزیع شخص ثالث نصب‌شده از طریق ابزارهایی مانند pip در پوشه‌ی site-packages پایتون عمل می‌کند. به‌طور مشخص، با توزیع‌هایی کار می‌کند که دارای پوشه‌های dist-info یا egg-info قابل‌کشف هستند، و نیز با فراداده‌ای که در مشخصات فراداده‌ی اصلی تعریف‌شده است.

مهم

این موارد لزوماً معادل یا متناظر یک‌به‌یک با نام‌های بسته ایمپورت سطح بالا که می‌توان آن‌ها را در کد پایتون ایمپورت کرد، نیستند. یک بسته توزیع می‌تواند شامل چندین بسته ایمپورت (و ماژول‌های منفرد) باشد، و یک بسته ایمپورت سطح بالا ممکن است در صورتی که یک بسته فضای نام باشد، به چندین بسته توزیع نگاشت شود. می‌توانید از packages_distributions() برای دریافت نگاشت بین آن‌ها استفاده کنید.

به‌طور پیش‌فرض، فراداده‌ی توزیع می‌تواند در سامانه فایل‌بندی یا در آرشیوهای zip موجود در sys.path قرار داشته باشد. از طریق یک سازوکار توسعه، فراداده می‌تواند تقریباً در هر جایی قرار داشته باشد.

همچنین ملاحظه نمائید

https://importlib-metadata.readthedocs.io/: مستندات importlib_metadata، که یک بک‌پورت از importlib.metadata را فراهم می‌کند. این مستندات شامل یک مرجع API برای کلاس‌ها و توابع این ماژول، و همچنین یک راهنمای مهاجرت برای کاربران فعلی pkg_resources است.

نمای کلی¶

فرض کنید می‌خواهید رشته نسخه را برای یک بسته توزیع (Distribution Package) که با استفاده از 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'

همچنین می‌توانید مجموعه‌ای از نقطه‌های ورودی را دریافت کنید که بر اساس ویژگی‌های EntryPoint (معمولاً 'group' یا 'name') قابل انتخاب هستند، مانند console_scripts، distutils.commands و دیگر موارد. هر گروه شامل مجموعه‌ای از اشیای EntryPoint است.

می‌توانید فراداده یک توزیع را دریافت کنید:

>>> from importlib.metadata import metadata
>>> 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¶: زیرکلاسی از ModuleNotFoundError که توسط چندین تابع در این ماژول، هنگام پرس‌وجو برای بسته توزیعی که در محیط پایتون جاری نصب نیست، پرتاب می‌شود.

exception importlib.metadata.MetadataNotFound¶: Subclass of FileNotFoundError raised when attempting to load metadata from a distribution folder that is empty or otherwise does not contain a metadata file.

API تابعی¶

این بسته، قابلیت‌های زیر را از طریق API عمومی خود فراهم می‌کند.

نقاط ورود¶

importlib.metadata.entry_points(**select_params)¶

نمونه‌ای از EntryPoints را برمی‌گرداند که نقاط ورود محیط جاری را توصیف می‌کند. هر پارامتر کلیدواژه‌ای که داده شود، به متد select() ارسال می‌شود تا با ویژگی‌های تعریف‌های جداگانه‌ی نقاط ورود مقایسه شود.

Note: to query for entry points based on EntryPoint.dist attribute, use Distribution.entry_points() instead (as different Distribution instances do not currently compare equal, even if they have the same attributes)

class importlib.metadata.EntryPoints¶

جزئیات مجموعه‌ای از نقاط ورودی نصب‌شده (entry points).

همچنین یک ویژگی .groups ارائه می‌دهد که تمام گروه‌های شناسایی‌شده‌ی نقطه ورود (entry point) را گزارش می‌دهد، و یک ویژگی .names که تمام نام‌های شناسایی‌شده‌ی نقطه ورود را گزارش می‌دهد.

class importlib.metadata.EntryPoint¶

جزئیات یک نقطه ورود نصب‌شده.

هر نمونه‌ی EntryPoint دارای ویژگی‌های .name، .group و .value و یک متد .load() برای حل کردن مقدار است. همچنین ویژگی‌های .module، .attr و .extras برای دریافت کامپوننت‌های ویژگی .value و نیز .dist برای به دست آوردن اطلاعات مربوط به بسته‌ی توزیعی که نقطه ورود را فراهم می‌کند، وجود دارند.

پرس‌وجوی همه‌ی نقطه‌های ورود:

>>> eps = entry_points()

تابع entry_points() یک شیء EntryPoints را برمی‌گرداند، مجموعه‌ای از تمام اشیای EntryPoint که برای سهولت دارای ویژگی‌های 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')

به‌طور معادل، از آنجا که entry_points() آرگومان‌های کلیدواژه‌ای را به 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: نقاط ورودی «قابل‌انتخاب» در importlib_metadata 3.6 و پایتون 3.10 معرفی شدند. پیش از آن تغییرات، entry_points هیچ پارامتری را نمی‌پذیرفت و همیشه یک دیکشنری از نقاط ورودی را برمی‌گرداند که بر اساس گروه کلیدگذاری شده بود. با importlib_metadata 5.0 و پایتون 3.12، entry_points همیشه یک شیء EntryPoints را برمی‌گرداند. برای گزینه‌های سازگاری، backports.entry_points_selectable را ببینید.

تغییر یافته در نسخه‌ی 3.13: اشیای EntryPoint دیگر رابطی شبیه به تاپل ارائه نمی‌دهند (__getitem__()).

فراداده‌ی توزیع¶

importlib.metadata.metadata(distribution_name)¶

فراداده توزیع مربوط به بسته توزیع نام‌برده‌شده را به‌عنوان یک نمونه از PackageMetadata برمی‌گرداند.

اگر بسته توزیع نام‌برده در محیط پایتون جاری نصب نشده باشد، PackageNotFoundError را پرتاب می‌کند.

Raises MetadataNotFound if a distribution package is present but no METADATA file is present.

class importlib.metadata.PackageMetadata¶

یک پیاده‌سازی عینی از پروتکل PackageMetadata.

علاوه بر ارائه متدها و ویژگی‌های تعریف‌شده‌ی پروتکل، اندیس‌گذاری نمونه معادل فراخوانی متد get() است.

هر بسته توزیع شامل فراداده‌ای است که می‌توانید آن را با استفاده از تابع metadata() استخراج کنید:

>>> wheel_metadata = metadata('wheel')

کلیدهای ساختار داده‌ی بازگردانده‌شده، نام کلیدواژه‌های فراداده هستند و مقادیر به‌صورت تجزیه‌نشده از فراداده‌ی توزیع بازگردانده می‌شوند:

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

PackageMetadata همچنین ویژگی json را ارائه می‌دهد که تمام فراداده‌ها را در قالبی سازگار با JSON مطابق PEP 566 برمی‌گرداند:

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

مجموعه‌ی کامل فراداده‌های موجود در اینجا توصیف نشده است. برای جزئیات بیشتر، Core metadata specification در PyPA را ببینید.

تغییر یافته در نسخه‌ی 3.15: Previously and incidentally, if a METADATA file was missing from a distribution, an empty PackageMetadata would be returned, indistinguishable from an empty METADATA file. Now, a missing METADATA file triggers a MetadataNotFound exception.

تغییر یافته در نسخه‌ی 3.10: Description اکنون هنگام ارائه از طریق بار در فراداده گنجانده شده است. نویسه‌های ادامه‌ی خط حذف شده‌اند.

ویژگی json افزوده شد.

نسخه‌های توزیع¶

importlib.metadata.version(distribution_name)¶

نسخه بسته توزیع نصب‌شده را برای بسته توزیع نام‌برده برمی‌گرداند.

اگر بسته توزیع نام‌برده در محیط پایتون جاری نصب نشده باشد، PackageNotFoundError را پرتاب می‌کند.

تابع version() سریع‌ترین راه برای دریافت شماره‌ی نسخه‌ی یک بسته توزیع به‌صورت یک رشته است:

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

پرونده‌های توزیع¶

importlib.metadata.files(distribution_name)¶

Return the full set of files contained within the named distribution package as PackagePath instances.

اگر بسته توزیع نام‌برده در محیط پایتون جاری نصب نشده باشد، PackageNotFoundError را پرتاب می‌کند.

اگر توزیع یافت شود اما رکوردهای پایگاه‌داده‌ی نصب که پرونده‌های مرتبط با بسته توزیع را گزارش می‌دهند موجود نباشند، مقدار None را برمی‌گرداند.

class importlib.metadata.PackagePath¶

A pathlib.PurePath derived object with additional dist, size, and hash properties corresponding to the distribution package's installation metadata for that file, also:

locate()¶: If possible, return the concrete SimplePath allowing to access data, or raise a NotImplementedError otherwise.

class importlib.metadata.SimplePath¶: A protocol representing a minimal subset of pathlib.Path that allows to check if it exists(), to traverse using joinpath() and parent, and to retrieve data using read_text() and read_bytes().

The files() function takes a Distribution Package name and returns all of the files installed by this distribution. 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

همچنین می‌توانید از متد locate() برای دریافت مسیر مطلق پرونده استفاده کنید:

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

در صورتی که پرونده فراداده‌ای که پرونده‌ها را فهرست می‌کند (RECORD یا SOURCES.txt) موجود نباشد، files() مقدار None را برمی‌گرداند. اگر معلوم نباشد که توزیع هدف دارای فراداده است، فراخواننده ممکن است بخواهد فراخوانی‌های files() را در always_iterable قرار دهد یا به روش دیگری در برابر این وضعیت محافظت کند.

نیازمندی‌های توزیع¶

importlib.metadata.requires(distribution_name)¶

مشخص‌کننده‌های وابستگی اعلام‌شده برای بسته توزیع نام‌برده را برمی‌گرداند.

اگر بسته توزیع نام‌برده در محیط پایتون جاری نصب نشده باشد، PackageNotFoundError را پرتاب می‌کند.

برای دریافت مجموعه کامل نیازمندی‌های یک بسته توزیع، از تابع requires() استفاده کنید:

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

نگاشت ایمپورت به بسته‌های توزیع¶

importlib.metadata.packages_distributions()¶

نگاشتی از نام ماژول‌های سطح بالا و بسته‌های ایمپورت که از طریق sys.meta_path یافت می‌شوند، به نام بسته‌های توزیع (در صورت وجود) که پرونده‌های متناظر را فراهم می‌کنند، برمی‌گرداند.

برای پشتیبانی از بسته‌های فضای نام (که ممکن است اعضای آن‌ها توسط چندین بسته توزیع فراهم شده باشند)، هر نام ایمپورت سطح بالا به فهرستی از نام‌های توزیع نگاشت می‌شود، نه اینکه به‌طور مستقیم به یک نام واحد نگاشت شود.

متدی آسان‌کننده برای تعیین نام بسته توزیع (یا نام‌ها، در مورد یک بسته فضای نام) که هر ماژول پایتون سطح‌بالای قابل ایمپورت یا بسته ایمپورت را فراهم می‌کنند:

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

برخی نصب‌های قابل‌ویرایش، نام‌های سطح بالا را ارائه نمی‌دهند، و بنابراین این تابع با چنین نصب‌هایی قابل‌اتکا نیست.

اضافه شده در نسخه‌ی 3.10.

توزیع‌ها¶

While the module level API described above is the most common and convenient usage, all that information is accessible from the Distribution class. Distribution is an abstract object that represents the metadata for a Python Distribution Package. Get the concrete 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'>

importlib.metadata.distribution(distribution_name)¶

نمونه‌ای از Distribution برمی‌گرداند که بسته توزیع نام‌برده‌شده را توصیف می‌کند.

اگر بسته توزیع نام‌برده در محیط پایتون جاری نصب نشده باشد، PackageNotFoundError را پرتاب می‌کند.

Thus, an alternative way to get e.g. the version number is through the Distribution.version attribute:

>>> dist.version
'0.32.3'

The same applies for entry_points() and files().

class importlib.metadata.Distribution¶

جزئیات یک بسته توزیع نصب‌شده.

توجه: نمونه‌های متفاوت Distribution در حال حاضر هنگام مقایسه برابر در نظر گرفته نمی‌شوند، حتی اگر به همان توزیع نصب‌شده مربوط باشند و بنابراین ویژگی‌های یکسانی داشته باشند.

static at(path)¶

classmethod from_name(name)¶: Return a Distribution instance at the given path or with the given name.

classmethod discover(*, context=None, **kwargs)¶

Returns an iterable of Distribution instances for all packages (see distribution-discovery).

The optional argument context is a DistributionFinder.Context instance, used to modify the search for distributions. Alternatively, kwargs may contain keyword arguments for constructing a new DistributionFinder.Context.

metadata: PackageMetadata¶

Raises MetadataNotFound if the METADATA file is not present in the distribution.

There are all kinds of additional metadata available on Distribution instances as a PackageMetadata instance:

>>> dist.metadata['Requires-Python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
>>> dist.metadata['License']
'MIT'

مجموعه‌ی کامل فراداده‌های موجود در اینجا توصیف نشده است. برای جزئیات بیشتر، Core metadata specification در PyPA را ببینید.

name: str¶

requires: list[str]¶

version: str¶: A few metadata fields are also available as shortcut properties.

اضافه شده در نسخه‌ی 3.10: The name shortcut was added.

origin¶

For editable packages, an origin property may present PEP 610 metadata (for non-editable packages, origin is None):

>>> dist.origin.url
'file:///path/to/wheel-0.32.3.editable-py3-none-any.whl'

The origin object follows the Direct URL Data Structure.

اضافه شده در نسخه‌ی 3.13.

entry_points: EntryPoints¶: The entry points provided by this distribution package.

files: list[PackagePath] | None¶: All files contained in this distribution package. Like files(), this returns None if there are no records.

The following two abstract methods need to be implemented when implementing-custom-providers:

locate_file(path)¶: Like PackagePath.locate(), return a SimplePath for the given path. Takes a os.PathLike or a str.

read_text(filename)¶: A shortcut for distribution.locate_file(filename).read_text().

کشف توزیع¶

به‌طور پیش‌فرض، این بسته پشتیبانی توکاری برای کشف فراداده‌ی بسته‌های توزیع در سامانه فایل‌بندی و پرونده‌های zip فراهم می‌کند. جست‌وجوی این یابنده‌ی فراداده به‌طور پیش‌فرض از sys.path استفاده می‌کند، اما تفسیر آن از این مقادیر، تفاوت اندکی با تفسیر سایر سازوکارهای ایمپورت دارد. به‌ویژه:

importlib.metadata اشیای bytes موجود در sys.path را به رسمیت نمی‌شناسد.
importlib.metadata به‌طور اتفاقی اشیای pathlib.Path موجود در sys.path را معتبر می‌شمارد، حتی اگر چنین مقادیری برای ایمپورت‌ها نادیده گرفته شوند.

class importlib.metadata.DistributionFinder¶

A MetaPathFinder subclass capable of discovering installed distributions.

Custom providers should implement this interface in order to supply metadata.

class Context(**kwargs)¶

A Context gives a custom provider a means to solicit additional details from the callers of distribution discovery functions like distributions() or Distribution.discover() beyond .name and .path when searching for distributions.

For example, a provider could expose suites of packages in either a "public" or "private" realm. A caller of distribution discovery functions may wish to query only for distributions in a particular realm and could call distributions(realm="private") to signal to the custom provider to only include distributions from that realm.

Each DistributionFinder must expect any parameters and should attempt to honor the canonical parameters defined below when appropriate.

See the section on پیاده‌سازی فراهم‌کنندگان سفارشی for more details.

name¶

Specific name for which a distribution finder should match.

A .name of None matches all distributions.

path¶

A property providing the sequence of directory paths that a distribution finder should search.

Typically refers to Python installed package paths such as "site-packages" directories and defaults to sys.path.

importlib.metadata.distributions(**kwargs)¶

Returns an iterable of Distribution instances for all packages.

The kwargs argument may contain either a keyword argument context, a DistributionFinder.Context instance, or pass keyword arguments for constructing a new DistributionFinder.Context. The DistributionFinder.Context is used to modify the search for distributions.

پیاده‌سازی فراهم‌کنندگان سفارشی¶

importlib.metadata دو سطح API را پوشش می‌دهد: یکی برای مصرف‌کنندگان و دیگری برای ارائه‌دهندگان. بیشتر کاربران مصرف‌کننده هستند و فراداده‌ی ارائه‌شده توسط بسته‌ها را مصرف می‌کنند. با این حال، موارد استفاده دیگری نیز وجود دارند که در آن‌ها کاربران می‌خواهند فراداده را از طریق سازوکار دیگری، مثلاً در کنار یک واردکننده سفارشی، در معرض قرار دهند. چنین مورد استفاده‌ای به یک ارائه‌دهنده سفارشی نیاز دارد.

از آن‌جا که فراداده‌ی بسته توزیعی از طریق جست‌وجوهای sys.path یا به‌طور مستقیم از طریق بارگذارهای بسته در دسترس نیست، فراداده‌ی یک توزیع از طریق یابنده‌ها در سیستم ایمپورت یافته می‌شود. برای یافتن فراداده‌ی یک بسته توزیعی، importlib.metadata فهرست یابنده‌های فرامسیر در sys.meta_path را جست‌وجو می‌کند.

این پیاده‌سازی دارای قلاب‌هایی (hooks) است که در PathFinder ادغام شده‌اند و فراداده بسته‌های توزیع یافت‌شده در سامانه پرونده را ارائه می‌کنند.

The abstract class importlib.abc.MetaPathFinder defines the interface expected of finders by Python's import system. importlib.metadata extends this protocol by looking for an optional find_distributions callable on the finders from sys.meta_path and presents this extended interface as the DistributionFinder abstract base class, which defines this abstract method:

@abc.abstractmethod
def find_distributions(context=DistributionFinder.Context()) -> Iterable[Distribution]:
    """پیمایش‌پذیری از همه نمونه‌های Distribution برمی‌گرداند که توانایی بارگذاری فراداده بسته‌ها برای ``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 sought by the consumer.

In practice, 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.

مثال¶

یک یابنده سفارشی را تصور کنید که ماژول‌های پایتون را از یک پایگاه داده بارگذاری می‌کند:

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)

به این ترتیب، query_distributions رکوردهایی را برای هر توزیع ارائه‌شده توسط پایگاه داده که با پرس‌وجو مطابقت دارد، بازمی‌گرداند. برای مثال، اگر requests-1.0 در پایگاه داده باشد، find_distributions یک DatabaseDistribution برای Context(name='requests') یا Context(name=None) تولید می‌کند.

برای سادگی، این مثال context.path را نادیده می‌گیرد. ویژگی path به‌طور پیش‌فرض برابر با sys.path است و مجموعه‌ای از مسیرهای ایمپورت است که در جستجو در نظر گرفته می‌شوند. یک DatabaseImporter به‌طور بالقوه می‌تواند بدون هیچ توجهی به مسیر جستجو کار کند. با فرض این‌که ایمپورت‌کننده هیچ بخش‌بندی انجام نمی‌دهد، «path» بی‌ارتباط خواهد بود. برای نشان دادن هدف از path، مثال باید یک DatabaseImporter پیچیده‌تر را نشان دهد که رفتار آن بسته به sys.path/PYTHONPATH تغییر می‌کند. در آن صورت، find_distributions باید context.path را رعایت کند و فقط نمونه‌های Distribution مرتبط با آن مسیر را برگرداند.

در این صورت، DatabaseDistribution چیزی شبیه به این خواهد بود:

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")

این پیاده‌سازی اولیه باید فراداده و نقاط ورود را برای بسته‌های ارائه‌شده توسط DatabaseImporter فراهم کند، با فرض اینکه record ویژگی‌های مناسب .name، .version و .entry_points را فراهم کند.

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.

`importlib.metadata` -- دسترسی به فراداده‌ی بسته¶

نمای کلی¶

API تابعی¶

نقاط ورود¶

فراداده‌ی توزیع¶

نسخه‌های توزیع¶

پرونده‌های توزیع¶

نیازمندی‌های توزیع¶

نگاشت ایمپورت به بسته‌های توزیع¶

توزیع‌ها¶

کشف توزیع¶

پیاده‌سازی فراهم‌کنندگان سفارشی¶

مثال¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه

importlib.metadata -- دسترسی به فراداده‌ی بسته¶

نمای کلی¶

API تابعی¶

نقاط ورود¶

فراداده‌ی توزیع¶

نسخه‌های توزیع¶

پرونده‌های توزیع¶

نیازمندی‌های توزیع¶

نگاشت ایمپورت به بسته‌های توزیع¶

توزیع‌ها¶

کشف توزیع¶

پیاده‌سازی فراهم‌کنندگان سفارشی¶

مثال¶

`importlib.metadata` -- دسترسی به فراداده‌ی بسته¶