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

Это добавит в __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.

Deprecated since version 3.3: This emulation is no longer needed, as the standard import mechanism is now fully PEP 302 compliant and available in importlib.

class pkgutil.ImpLoader(fullname, file, filename, etc)¶

Loader оборачивающий «классический» алгоритм импорта Python.

Deprecated since version 3.3: This emulation is no longer needed, as the standard import mechanism is now fully PEP 302 compliant and available in importlib.

pkgutil.find_loader(fullname)¶

Возвращает загрузчик модуля loader для указанного fullname.

Это обёртка обратной совместимости для importlib.util.find_spec(), которая преобразует большинство ошибок в ImportError и возвращает только загрузчик, а не полный ModuleSpec.

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

Изменено в версии 3.4: Обновлено для использования на основе PEP 451

pkgutil.get_importer(path_item)¶

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

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

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

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

pkgutil.get_loader(module_or_name)¶

Возвращает объект загрузчика для module_or_name.

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

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

Изменено в версии 3.4: Обновлено для использования на основе PEP 451

pkgutil.iter_importers(fullname='')¶

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

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

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

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

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

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

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

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

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

Примечание

Работает только для finder, который определяет метод 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__ для поиска подмодулей.

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

Примеры:

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

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

Примечание

Работает только для finder, который определяет метод 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.

pkgutil.resolve_name(name)¶

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

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

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

• W(.W)*

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

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

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

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

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

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

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

Новое в версии 3.9.