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

Исходный код: Lib/pkgutil.py

Этот модуль предоставляет утилиты для системы импорта, в частности, для поддержки пакетов.

class pkgutil.ModuleInfo(module_finder, name, ispkg): namedtuple, содержащий краткое описание информации о модуле.

Добавлен в версии 3.6.

pkgutil.extend_path(path, name)

Расширить путь поиска модулей, составляющих пакет. Предполагается, что следующий код размещён в каталоге пакета:

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

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

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

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

pkgutil.find_loader(fullname)

Получить загрузчик модуля для данного 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)

Получить поисковик для заданного path_item.

Возвращённый поисковик кэшируется в sys.path_importer_cache, если он был создан новым обработчиком путей.

Кэш (или его часть) можно очистить вручную, если необходимо пересканировать sys.path_hooks.

pkgutil.get_loader(module_or_name)

Получить объект загрузчика для module_or_name.

Если модуль или пакет доступны через обычный механизм импорта, возвращается обёртка вокруг соответствующей части этого механизма. Возвращает None, если модуль не найден или не может быть импортирован. Если названный модуль ещё не импортирован, импортируется содержащий его пакет (если таковой имеется), чтобы установить пакет __path__.

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

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

pkgutil.iter_importers(fullname='')

Возвращает итератор поисковиков для данного имени модуля.

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

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

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

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

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

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

prefix — строка, которая добавляется в начало каждого имени модуля на выходе.

Примечание

Работает только с поисковиком, который определяет метод iter_modules(). Этот интерфейс нестандартный, поэтому модуль также предоставляет реализации для importlib.machinery.FileFinder и zipimport.zipimporter.

END_OF_DOCUMENT_MARKER

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

Возвращает ModuleInfo для всех модулей рекурсивно по path, или, если path является None, все доступные модули.

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

prefix — строка, добавляемая в начало каждого имени модуля на выходе.

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

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

Примеры:

# list all modules python can access
walk_packages()

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

Примечание

Работает только для найдителя, который определяет метод iter_modules(). Этот интерфейс нестандартный, поэтому модуль также предоставляет реализации для importlib.machinery.FileFinder и zipimport.zipimporter.

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

pkgutil.get_data(package, resource)

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

Это обёртка для API загрузчика get_data. Аргумент package должен быть именем пакета в стандартном формате модуля (foo.bar). Аргумент resource должен быть в формате относительного имени файла, используя / в качестве разделителя пути. Имя родительского каталога .. не разрешено, как и имя с корнем (начинающееся с /).

Функция возвращает двоичную строку, содержащую содержимое указанного ресурса.

Для пакетов, расположенных в файловой системе, которые уже были импортированы, это примерно эквивалентно:

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

Если пакет не может быть найден или загружен, или он использует загрузчик, который не поддерживает get_data, то возвращается None. В частности, загрузчик для пакетов именного пространства не поддерживает get_data.

pkgutil.resolve_name(name)

Разрешение имени до объекта.

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

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

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

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

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

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

ValueError — если name не имеет распознаваемого формата.

ImportError — если произошёл импорт, когда он не должен был.

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

Добавлена в версии 3.9.