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

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

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

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='')

Возвращает итератор по (module_finder, name, ispkg) для всех подмодулей в 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)

Возвращает (module_finder, name, ispkg) для всех модулей рекурсивно по 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.