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.find_loader(fullname)

Отримати модуль loader для вказаного повного імені.

This is a backwards compatibility wrapper around importlib.util.find_spec() that converts most failures to ImportError and only returns the loader rather than the full importlib.machinery.ModuleSpec.

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

Змінено в версії 3.4: Оновлено на основі PEP 451

Deprecated since version 3.12, will be removed in version 3.14: Натомість використовуйте importlib.util.find_spec().

pkgutil.get_importer(path_item)

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

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

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

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

pkgutil.get_loader(module_or_name)

Отримайте об’єкт loader для module_or_name.

Якщо модуль або пакет доступні через звичайний механізм імпорту, повертається обгортка навколо відповідної частини цього механізму. Повертає None, якщо модуль неможливо знайти або імпортувати. Якщо вказаний модуль ще не імпортовано, його пакет (якщо є) імпортується, щоб створити пакет __path__.

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

Змінено в версії 3.4: Оновлено на основі PEP 451

Deprecated since version 3.12, will be removed in version 3.14: Натомість використовуйте importlib.util.find_spec().

pkgutil.iter_importers(fullname='')

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

Якщо повне ім’я містить '.', 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)

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

Це оболонка для API loader get_data. Аргумент package має бути назвою пакета в стандартному форматі модуля (foo.bar). Аргумент resource має бути у формі відносного імені файлу, використовуючи / як роздільник шляху. Ім’я батьківського каталогу .. не допускається, а також коренева назва (починається з /).

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

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

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

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

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.