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

Для каждого каталога в 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.

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__ + '.')

Примечание

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.