pkgutil — Package extension utility

Вихідний код: Lib/pkgutil.py

---

Цей модуль надає утиліти для системи імпорту, зокрема підтримку пакетів.

class pkgutil.ModuleInfo(module_finder, name, ispkg)

Іменований кортеж, який містить короткий опис інформації про модуль.

Added in version 3.6.

pkgutil.extend_path(path, name)

Розширте шлях пошуку для модулів, які складають пакет. Цільове використання – розмістити наступний код у __init__.py:

from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

For each directory on sys.path that has a subdirectory that matches the package name, add the subdirectory to the package’s __path__. This is useful if one wants to distribute different parts of a single logical package as multiple directories.

It also looks for *.pkg files beginning where * matches the name argument. This feature is similar to *.pth files (see the site module for more information), except that it doesn’t special-case lines starting with import. A *.pkg file is trusted at face value: apart from skipping blank lines and ignoring comments, all entries found in a *.pkg file are added to the path, regardless of whether they exist on the filesystem (this is a feature).

Якщо шлях введення не є списком (як у випадку заморожених пакунків), він повертається без змін. Вхідний шлях не змінено; повертається розширена копія. Елементи додаються до копії лише в кінці.

Передбачається, що sys.path є послідовністю. Елементи sys.path, які не є рядками, що посилаються на існуючі каталоги, ігноруються. Елементи Юнікоду в sys.path, які спричиняють помилки, коли використовуються як імена файлів, можуть викликати виняток у цій функції (відповідно до поведінки os.path.isdir()).

pkgutil.get_importer(path_item)

Отримати finder для заданого path_item.

Повернений засіб пошуку зберігається в sys.path_importer_cache, якщо він був щойно створений за допомогою перехоплювача шляху.

Кеш (або його частину) можна очистити вручну, якщо потрібно повторне сканування sys.path_hooks.

Змінено в версії 3.3: Оновлено, щоб базуватися безпосередньо на importlib, а не на внутрішній емуляції імпорту PEP 302 пакета.

pkgutil.iter_importers(fullname='')

Видає об’єкти finder для вказаного імені модуля.

If fullname contains a '.', the finders will be for the package containing fullname, otherwise they will be all registered top level finders (i.e. those on both sys.meta_path and sys.path_hooks).

Якщо вказаний модуль міститься в пакеті, цей пакет імпортується як побічний ефект виклику цієї функції.

Якщо ім’я модуля не вказано, створюються всі шукачі верхнього рівня.

Змінено в версії 3.3: Оновлено, щоб базуватися безпосередньо на importlib, а не на внутрішній емуляції імпорту PEP 302 пакета.

pkgutil.iter_modules(path=None, prefix='')

Видає ModuleInfo для всіх підмодулів на path або, якщо path має значення None, усі модулі верхнього рівня на sys.path.

path має бути або None, або список шляхів для пошуку модулів.

префікс — це рядок, який виводиться на початку кожного імені модуля при виведенні.

Примітка

Працює лише для finder, який визначає метод iter_modules(). Цей інтерфейс є нестандартним, тому модуль також забезпечує реалізації для importlib.machinery.FileFinder і zipimport.zipimporter.

Змінено в версії 3.3: Оновлено, щоб базуватися безпосередньо на importlib, а не на внутрішній емуляції імпорту PEP 302 пакета.

pkgutil.walk_packages(path=None, prefix='', onerror=None)

Видає ModuleInfo для всіх модулів рекурсивно за шляхом або, якщо шлях має значення None, усі доступні модулі.

path має бути або None, або список шляхів для пошуку модулів.

префікс — це рядок, який виводиться на початку кожного імені модуля при виведенні.

Зауважте, що ця функція має імпортувати всі пакети (не всі модулі!) за вказаним шляхом, щоб отримати доступ до атрибута __path__ для пошуку підмодулів.

onerror — це функція, яка викликається з одним аргументом (назва пакета, який імпортувався), якщо під час спроби імпортувати пакет виникає будь-яка виняткова ситуація. Якщо функція onerror не надається, ImportErrors перехоплюються та ігноруються, тоді як усі інші винятки поширюються, припиняючи пошук.

Приклади:

# list all modules python can access
walk_packages()

# list all submodules of ctypes
walk_packages(ctypes.__path__, ctypes.__name__ + '.')

Примітка

Працює лише для finder, який визначає метод iter_modules(). Цей інтерфейс є нестандартним, тому модуль також забезпечує реалізації для importlib.machinery.FileFinder і zipimport.zipimporter.

Змінено в версії 3.3: Оновлено, щоб базуватися безпосередньо на importlib, а не на внутрішній емуляції імпорту PEP 302 пакета.

pkgutil.get_data(package, resource)

Отримати ресурс із пакету.

This is a wrapper for the loader get_data API. The package argument should be the name of a package, in standard module format (foo.bar). The resource argument should be in the form of a relative filename, using / as the path separator.

Функція повертає двійковий рядок, який є вмістом зазначеного ресурсу.

This function uses the loader method get_data() to support modules installed in the filesystem, but also in zip files, databases, or elsewhere.

Для пакетів, розташованих у файловій системі, які вже були імпортовані, це приблизний еквівалент:

d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()

Like the open() function, get_data() can follow parent directories (../) and absolute paths (starting with / or C:/, for example). It can open compilation/installation artifacts like .py and .pyc files or files with reserved filenames. To be compatible with non-filesystem loaders, avoid using these features.

Попередження

This function is intended for trusted input. It does not verify that resource «belongs» to package.

If you use a user-provided resource path, consider verifying it. For example, require an alphanumeric filename with a known extension, or install and check a list of known resources.

Якщо пакет не вдається знайти або завантажити, або він використовує loader, який не підтримує get_data, повертається None. Зокрема, loader для пакетів простору імен не підтримує get_data.

Дивись також

The importlib.resources module provides structured access to module resources.

pkgutil.resolve_name(name)

Розв’яжіть ім’я з об’єктом.

Ця функціональність використовується в багатьох місцях у стандартній бібліотеці (див. bpo-12915), а еквівалентна функціональність також є в широко використовуваних пакетах сторонніх розробників, таких як setuptools, Django та Pyramid.

Очікується, що ім’я буде рядком в одному з таких форматів, де W є скороченням дійсного ідентифікатора Python, а крапка означає крапку в цих псевдорегулярних виразах:

• W(.W)*

• W(.W)*:(W(.W)*)?

Перша форма призначена лише для зворотної сумісності. Припускається, що деяка частина назви з крапками є пакетом, а решта є об’єктом десь у цьому пакеті, можливо, вкладеним в інші об’єкти. Оскільки місце, де зупиняється пакет і починається ієрархія об’єктів, не може бути встановлено шляхом перевірки, повторні спроби імпорту потрібно робити за допомогою цієї форми.

У другій формі абонент чітко пояснює точку розділення за допомогою однієї двокрапки: назва з крапками ліворуч від двокрапки означає пакет, який потрібно імпортувати, а назва з крапками праворуч — це ієрархія об’єктів у цьому пакеті. . У цій формі потрібен лише один імпорт. Якщо він закінчується двокрапкою, повертається об’єкт модуля.

Функція поверне об’єкт (який може бути модулем) або викличе одне з таких винятків:

ValueError – якщо ім’я не в розпізнаному форматі.

ImportError – якщо імпорт не вдався, а не мав бути.

AttributeError – Якщо сталася помилка під час проходження ієрархії об’єктів в імпортованому пакеті, щоб дістатися до потрібного об’єкта.

Added in version 3.9.