`pkgutil` – Утилита расширения пакетов¶pkgutil – Package extension utility

Исходный код: 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__)

Для каждого каталога из sys.path, содержащего подкаталог, имя которого совпадает с именем пакета, этот подкаталог добавляется в __path__ пакета. Это полезно, если требуется распространять разные части одного логического пакета в виде нескольких каталогов.

Также выполняется поиск файлов *.pkg, начиная с тех, где * соответствует аргументу name. Эта возможность похожа на файлы *.pth (см. модуль site для подробностей), за исключением того, что строки, начинающиеся с import, не обрабатываются особым образом. Файл *.pkg принимается как есть: помимо пропуска пустых строк и игнорирования комментариев, все записи, найденные в файле *.pkg, добавляются в путь, независимо от того, существуют ли они в файловой системе (это особенность).

Если входной путь не является списком (как в случае замороженных пакетов), он возвращается без изменений. Входной путь не модифицируется; возвращается расширенная копия. Элементы добавляются только в конец этой копии.

Предполагается, что sys.path является последовательностью. Элементы sys.path, которые не являются строками, ссылающимися на существующие каталоги, игнорируются. Элементы Unicode в sys.path, вызывающие ошибки при использовании в качестве имён файлов, могут привести к возникновению исключения этой функцией (в соответствии с поведением os.path.isdir()).

pkgutil.get_importer(path_item)¶

Возвращает объект finder для указанного path_item.

Возвращённый объект finder кэшируется в sys.path_importer_cache, если он был только что создан хуком пути.

Кэш (или его часть) можно очистить вручную, если требуется повторное сканирование sys.path_hooks.

Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на importlib вместо использования внутренней эмуляции импорта PEP 302 пакета.

pkgutil.iter_importers(fullname='')¶

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

Если fullname содержит '.', то поисковики будут относиться к пакету, содержащему fullname; в противном случае будут возвращены все зарегистрированные поисковики верхнего уровня (то есть те, что находятся в sys.meta_path и sys.path_hooks).

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

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

pkgutil.iter_modules(path=None, prefix='')¶

Возвращает ModuleInfo для всех подмодулей в path, или, если path равно None, все модули верхнего уровня из sys.path.

path должен быть либо None, либо списком путей для поиска модулей.

prefix – это строка, которая выводится перед именем каждого модуля в выводе.

Примечание

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

pkgutil.walk_packages(path=None, prefix='', onerror=None)¶

Возвращает ModuleInfo для всех модулей рекурсивно в path, или, если path равно None, всех доступных модулей.

path должен быть либо None, либо списком путей для поиска модулей.

prefix – это строка, которая выводится перед именем каждого модуля в выводе.

Обратите внимание, что эта функция должна импортировать все пакеты (не все модули!) по заданному пути, чтобы получить доступ к атрибуту __path__ для поиска подмодулей.

onerror – это функция, которая вызывается с одним аргументом (именем пакета, который импортировался), если при попытке импортировать пакет возникает исключение. Если функция onerror не указана, то ImportError перехватываются и игнорируются, а все остальные исключения распространяются, прекращая поиск.

Примеры:

# вывести все модули, доступные Python
walk_packages()

# вывести все подмодули ctypes
walk_packages(ctypes.__path__, ctypes.__name__ + '.')

Примечание

pkgutil.get_data(package, resource)¶

Получить ресурс из пакета.

Это обёртка для API загрузчика get_data. Аргумент package должен быть именем пакета в стандартном формате модуля (foo.bar). Аргумент resource должен быть в виде относительного имени файла, с использованием / в качестве разделителя пути.

Функция возвращает двоичную строку, содержащую указанный ресурс.

Эта функция использует метод загрузчика get_data(), чтобы поддерживать модули, установленные в файловой системе, а также в zip-файлах, базах данных или других местах.

Для пакетов, расположенных в файловой системе, которые уже были импортированы, это приблизительный эквивалент следующего:

d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()

Как и функция open(), get_data() может переходить по родительским каталогам (../) и абсолютным путям (начинающимся с / или C:/, например). Она может открывать артефакты компиляции/установки, такие как файлы .py и .pyc или файлы с reserved filenames. Для совместимости с загрузчиками, не основанными на файловой системе, избегайте использования этих возможностей.

Предупреждение

Эта функция предназначена для доверенных входных данных. Она не проверяет, что resource «принадлежит» package.

При использовании предоставленного пользователем пути resource рекомендуется его проверять. Например, требовать алфавитно-цифровое имя файла с известным расширением или установить и проверять список известных ресурсов.

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

См. также

Модуль importlib.resources предоставляет структурированный доступ к ресурсам модулей.

pkgutil.resolve_name(name, *, strict=False)¶

Разрешить имя в объект.

Эта функциональность используется во многих местах стандартной библиотеки (см. bpo-12915) – и эквивалентная функциональность также имеется в широко используемых сторонних пакетах, таких как setuptools, Django и Pyramid.

Ожидается, что name будет строкой в одном из следующих форматов, где W – сокращение для допустимого идентификатора Python, а точка обозначает литеральную точку в этих псевдорегулярных выражениях:

W(.W)*
W(.W)*:(W(.W)*)?
W(.W)*:(W(.W)*)

Первая форма предназначена только для обратной совместимости. Она предполагает, что некоторая часть точечного имени является пакетом, а остальное – объект где-то внутри этого пакета, возможно, вложенный в другие объекты. Поскольку место, где заканчивается пакет и начинается иерархия объектов, невозможно определить путём анализа, при использовании этой формы приходится выполнять многократные попытки импорта.

Во второй форме вызывающий код указывает точку разделения с помощью одного двоеточия: точечное имя слева от двоеточия – это пакет, который нужно импортировать, а точечное имя справа – это иерархия объектов внутри этого пакета. В этой форме требуется только один импорт. Если имя заканчивается двоеточием, возвращается объект модуля.

Первые две формы принимаются, когда strict=False (по умолчанию).

Третья форма требует и имя модуля, и вызываемый объект, разделённые двоеточием. Только эта форма принимается, когда strict=True.

Функция возвращает объект (который может быть модулем) или возбуждает одно из следующих исключений:

ValueError – если name не в распознаваемом формате.

ImportError – если импорт не удался, хотя не должен был.

AttributeError – если произошла ошибка при обходе иерархии объектов внутри импортированного пакета для достижения нужного объекта.

Добавлено в версии 3.9.

Изменено в версии 3.15: Был добавлен необязательный параметр только-по-ключу strict.

pkgutil – Утилита расширения пакетов¶pkgutil – Package extension utility

`pkgutil` – Утилита расширения пакетов¶pkgutil – Package extension utility