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.

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

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

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

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.