pkgutil — Утилита расширения пакетов

Исходный код: Lib/pkgutil.py

Этот модуль предоставляет утилиты для системы импорта, в частности, для поддержки пакетов.

class pkgutil.ModuleInfo(module_finder, name, ispkg): Namedtuple, содержащий краткое описание информации о модуле.

Новая в версии 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='')

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

Если имя модуля содержит «.», искатели будут для пакета, содержащего имя модуля; в противном случае они будут для всех зарегистрированных искателей верхнего уровня (т.е. тех, которые находятся как в 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__ + '.')

Примечание

Работает только для поисковика, который определяет метод iter_modules(). Этот интерфейс нестандартный, поэтому модуль также предоставляет реализации для importlib.machinery.FileFinder и zipimport.zipimporter.

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