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.

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

Примечание

Изменено в версии 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.