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()).

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 и возвращает только загрузчик, а не весь importlib.machinery.ModuleSpec.

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

Изменено в версии 3.4: Обновлено, чтобы базироваться на PEP 451

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

pkgutil.iter_importers(fullname='')

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

Если fullname содержит '.', поисковики будут для пакета, содержащего fullname, иначе будут все зарегистрированные поисковики верхнего уровня (т. е. те, что находятся как в sys.meta_path, так и в sys.path_hooks).

Если названный модуль находится в пакете, этот пакет импортируется в качестве побочного эффекта вызова этой функции.

Если имя модуля не указано, генерируются все поисковики верхнего уровня.

END_OF_DOCUMENT_MARKER

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

Примечание

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.