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

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

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

class pkgutil.ModuleInfo(module_finder, name, ispkg)¶

Именованный элемент, содержащий краткую информацию о модуле.

Добавлено в версии 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, которые не являются строками, ссылающимися на существующие каталоги, игнорируются. Элементы Юникода в sys.path, которые вызывают ошибки при использовании в качестве имен файлов, могут привести к тому, что эта функция вызовет исключение (в соответствии с поведением os.path.isdir()).

class pkgutil.ImpImporter(dirname=None)¶

PEP 302 Поисковик, который использует «классический» алгоритм импорта Python.

Если dirname является строкой, создается PEP 302 finder, который выполняет поиск в этом каталоге. Если dirname равно None, создается PEP 302 программа поиска, которая выполняет поиск по текущему sys.path, а также по любым модулям, которые заморожены или встроены.

Обратите внимание, что ImpImporter в настоящее время не поддерживается для использования при размещении на sys.meta_path.

Не рекомендуется, начиная с версии 3.3: Эта эмуляция больше не нужна, так как стандартный механизм импорта теперь полностью совместим с PEP 302 и доступен в importlib.

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

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

Не рекомендуется, начиная с версии 3.3: Эта эмуляция больше не нужна, так как стандартный механизм импорта теперь полностью совместим с PEP 302 и доступен в importlib.

pkgutil.find_loader(fullname)¶

Извлеките модуль loader для данного полного имени.

Это оболочка обратной совместимости для importlib.util.find_spec(), которая преобразует большинство сбоев в ImportError и возвращает только загрузчик, а не полный importlib.machinery.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)¶

Получаем loader объект для module_or_name.

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

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

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

pkgutil.iter_importers(fullname='')¶

Получите finder объектов для заданного имени модуля.

Если 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, либо списком путей для поиска модулей.

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

Примечание

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

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

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

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

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

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

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

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

Примеры:

# list all modules python can access
walk_packages()

# list all submodules of 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)¶

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

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

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

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

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

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

pkgutil.resolve_name(name)¶

Присвоить имя объекту.

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

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

• W(.W)*

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

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

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

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

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

ImportError – если импорт завершился неудачей, когда этого не должно было произойти.

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

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