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

pkgutil.get_loader(module_or_name)

Получить объект загрузчика для module_or_name.

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

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

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

Примечание

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