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, которые не являются строками, относящимися к существующим каталогам, игнорируются. Элементы Unicode в 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='')

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

Если 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 — строка, которая добавляется в начало имени каждого модуля на выходе.

Примечание

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

Примеры:

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