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

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

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

class pkgutil.ModuleInfo(module_finder, name, ispkg)¶

Именованный кортеж, содержащий краткую информацию о модуле.

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

pkgutil.extend_path(path, name)¶

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

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

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

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

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

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

class pkgutil.ImpImporter(dirname=None)¶

PEP 302 Поиск, который обертывает «классический» алгоритм импорта Python.

Если dirname - строка, создается поисковый модуль PEP 302, который ищет в этом каталоге. Если dirname равно None, создается искатель PEP 302, который ищет в текущем каталоге sys.path, плюс все модули, которые заморожены или встроены.

Обратите внимание, что ImpImporter в настоящее время не поддерживает использование при размещении на sys.meta_path.

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

class pkgutil.ImpLoader(fullname, file, filename, etc)¶

Loader, который обертывает «классический» алгоритм импорта Python.

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

pkgutil.find_loader(fullname)¶

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

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

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

Изменено в версии 3.4: Обновлено на основе PEP 451.

pkgutil.get_importer(path_item)¶

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

Возвращенный 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.

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 для всех подмодулей на пути, или, если путь равен 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 не задана, то 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 для namespace packages не поддерживает 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.