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

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

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

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.