pkgutil — Утилиты для системы импорта

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

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)

Загрузчик, обертывающий «классический» алгоритм импорта Python.

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

pkgutil.find_loader(fullname)

Получить модуль загрузчика для заданного fullname.

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

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

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

pkgutil.get_importer(path_item)

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

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

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

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

pkgutil.get_loader(module_or_name)

Возвращает объект загрузчика для module_or_name.

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

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

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

pkgutil.iter_importers(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 — это строка, которая выводится перед каждым именем модуля на выходе.

Примечание

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

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

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

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

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

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

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

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

Примеры:

# перечислить все модули, к которым может получить доступ python
walk_packages()

# перечислить все подмодули 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.