pkgutil — Утилита расширения пакета

Kod źródłowy: Lib/pkgutil.py

---

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

class pkgutil.ModuleInfo(module_finder, name, ispkg)

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

Dodane w wersji 3.6.

pkgutil.extend_path(path, name)

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

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

Для каждого каталога в sys.path, у которого есть подкаталог, соответствующий имени пакета, добавьте подкаталог в __path__ пакета. Это полезно, если вы хотите распределить разные части одного логического пакета по нескольким каталогам.

Он также ищет файлы *.pkg, начинающиеся с которых * соответствует аргументу name. Эта функция аналогична файлам *.pth (дополнительную информацию см. в модуле site), за исключением того, что в ней нет специальных строк, начинающихся с import. Файлу *.pkg доверяют по номинальной стоимости: помимо пропуска пустых строк и игнорирования комментариев, все записи, найденные в файле *.pkg, добавляются к пути, независимо от того, они существуют в файловой системе (это особенность).

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

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

pkgutil.find_loader(fullname)

Retrieve a module loader for the given fullname.

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.

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

Zmienione w wersji 3.4: Updated to be based on PEP 451

Deprecated since version 3.12, will be removed in version 3.14: Use importlib.util.find_spec() instead.

pkgutil.get_importer(path_item)

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

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

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

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

pkgutil.get_loader(module_or_name)

Get a loader object for module_or_name.

If the module or package is accessible via the normal import mechanism, a wrapper around the relevant part of that machinery is returned. Returns None if the module cannot be found or imported. If the named module is not already imported, its containing package (if any) is imported, in order to establish the package __path__.

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

Zmienione w wersji 3.4: Updated to be based on PEP 451

Deprecated since version 3.12, will be removed in version 3.14: Use importlib.util.find_spec() instead.

pkgutil.iter_importers(fullname='')

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

Se fullname contiver '.', os localizadores serão para o pacote que contém fullname, caso contrário, serão todos os localizadores de nível superior registrados (ou seja, aqueles em sys.meta_path e sys.path_hooks).

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

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

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

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

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

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

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

Informacja

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

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

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

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

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

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

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

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

Przykłady:

# list all modules python can access
walk_packages()

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

Informacja

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

Zmienione w wersji 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 – Якщо сталася помилка під час проходження ієрархії об’єктів в імпортованому пакеті, щоб дістатися до потрібного об’єкта.

Dodane w wersji 3.9.