pkgutil
— Утилита для расширения пакетов¶
Источник: Lib/pkgutil.py
Этот модуль предоставляет утилиты для системы импорта, в частности, поддержку пакетов.
- class pkgutil.ModuleInfo(module_finder, name, ispkg)¶
Именованный кортеж, содержащий краткую информацию о модуле.
Added in version 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()
).
- pkgutil.find_loader(fullname)¶
Получение модуля loader для заданного fullname.
Это обертка для обратной совместимости с
importlib.util.find_spec()
, которая преобразует большинство сбоев вImportError
и возвращает только загрузчик, а не полныйimportlib.machinery.ModuleSpec
.Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на
importlib
, а не полагаться на эмуляцию импорта внутренней части пакета PEP 302.Изменено в версии 3.4: Обновлено, чтобы основываться на PEP 451
Утратил актуальность с версии 3.12, удален в версии 3.14: Вместо этого используйте
importlib.util.find_spec()
.
- pkgutil.get_importer(path_item)¶
Получение finder для данного путь_элемента.
Возвращенный искатель кэшируется в
sys.path_importer_cache
, если он был создан недавно с помощью крючка пути.Кэш (или его часть) можно очистить вручную, если требуется повторное сканирование
sys.path_hooks
.
- pkgutil.get_loader(module_or_name)¶
Получить объект loader для module_or_name.
Если модуль или пакет доступен через обычный механизм импорта, возвращается обертка вокруг соответствующей части этого механизма. Возвращает
None
, если модуль не может быть найден или импортирован. Если именованный модуль еще не импортирован, импортируется содержащий его пакет (если таковой имеется), чтобы создать пакет__path__
.Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на
importlib
, а не полагаться на эмуляцию импорта внутренней части пакета PEP 302.Изменено в версии 3.4: Обновлено, чтобы основываться на PEP 451
Утратил актуальность с версии 3.12, удален в версии 3.14: Вместо этого используйте
importlib.util.find_spec()
.
- 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
для всех модулей, рекурсивно лежащих на пути, или, если путь равенNone
, все доступные модули.path должен быть либо
None
, либо список путей, по которым следует искать модули.prefix - это строка, которую нужно выводить перед именем каждого модуля при выводе.
Обратите внимание, что эта функция должна импортировать все пакеты (не все модули!) на заданном пути, чтобы получить доступ к атрибуту
__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
.
- 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
– Если при обходе иерархии объектов в импортированном пакете произошел сбой, чтобы добраться до нужного объекта.Added in version 3.9.