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

Источник: 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__)

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

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

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

Предполагается, что sys.path - это последовательность. Элементы sys.path, не являющиеся строками, ссылающимися на существующие каталоги, игнорируются. Элементы Юникода в sys.path, которые вызывают ошибки при использовании в качестве имен файлов, могут привести к тому, что эта функция вызовет исключение (в соответствии с поведением os.path.isdir()).

pkgutil.find_loader(fullname)

Получение модуля loader для заданного fullname.

Это обертка для обратной совместимости с importlib.util.find_spec(), которая преобразует большинство сбоев в ImportError и возвращает только загрузчик, а не полный importlib.machinery.ModuleSpec.

Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на importlib, а не полагаться на эмуляцию импорта внутренней части пакета PEP 302.

Изменено в версии 3.4: Обновлено, чтобы основываться на PEP 451

Утратил актуальность с версии 3.12, удален в версии 3.14: Вместо этого используйте importlib.util.find_spec().

pkgutil.get_importer(path_item)

Получение finder для данного путь_элемента.

Возвращенный искатель кэшируется в 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

Утратил актуальность с версии 3.12, удален в версии 3.14: Вместо этого используйте importlib.util.find_spec().

pkgutil.iter_importers(fullname='')

Выдает finder объектов для заданного имени модуля.

Если fullname содержит '.', то поиск будет осуществляться для пакета, содержащего fullname, в противном случае это будут все зарегистрированные поисковые системы верхнего уровня (т.е. те, которые находятся и в sys.meta_path, и в sys.path_hooks).

Если именованный модуль находится в пакете, то этот пакет импортируется как побочный эффект вызова этой функции.

Если имя модуля не указано, будут созданы все поисковые системы верхнего уровня.

Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на importlib, а не полагаться на эмуляцию импорта внутренней части пакета PEP 302.

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

Выдает ModuleInfo для всех подмодулей на path, или, если path - это None, все модули верхнего уровня на sys.path.

path должен быть либо None, либо список путей, по которым следует искать модули.

prefix - это строка, которую нужно выводить перед именем каждого модуля при выводе.

Примечание

Работает только для 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, либо список путей, по которым следует искать модули.

prefix - это строка, которую нужно выводить перед именем каждого модуля при выводе.

Обратите внимание, что эта функция должна импортировать все пакеты (не все модули!) на заданном пути, чтобы получить доступ к атрибуту __path__ для поиска подмодулей.

onerror - это функция, которая вызывается с одним аргументом (именем импортируемого пакета), если при попытке импортировать пакет возникает какое-либо исключение. Если функция onerror не указана, то ImportErrorперехватывается и игнорируется, а все остальные исключения распространяются, завершая поиск.

Примеры:

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

Получение ресурса из пакета.

Это обертка для loader get_data API. Аргумент 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 для namespace packages не поддерживает get_data.

pkgutil.resolve_name(name)

Соотнесите имя с объектом.

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

Ожидается, что name будет строкой в одном из следующих форматов, где W - сокращение для действительного идентификатора Python, а точка обозначает буквенную точку в этих псевдорегексах:

• W(.W)*

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

Первая форма предназначена только для обратной совместимости. Она предполагает, что некоторая часть точечного имени является пакетом, а остальное - объектом где-то внутри этого пакета, возможно, вложенным в другие объекты. Поскольку место, где заканчивается пакет и начинается иерархия объектов, не может быть определено путем осмотра, повторные попытки импорта должны выполняться с помощью этой формы.

Во второй форме вызывающая сторона делает точку разделения ясной с помощью единственного двоеточия: имя с точкой слева от двоеточия - это пакет, который нужно импортировать, а имя с точкой справа - это иерархия объектов в этом пакете. В этой форме требуется только один импорт. Если он заканчивается двоеточием, то возвращается объект модуля.

Функция вернет объект (который может быть модулем) или вызовет одно из следующих исключений:

ValueError – если имя не имеет распознанного формата.

ImportError – если импорт не удался, когда этого не должно было произойти.

AttributeError – Если при обходе иерархии объектов в импортированном пакете произошел сбой, чтобы добраться до нужного объекта.

Added in version 3.9.