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

pkgutil.find_loader(fullname)

Получает загрузчик модуля с указанным полным именем (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)

Получает средство поиска для указанного элемента пути (path_item).

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

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

pkgutil.get_loader(module_or_name)

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

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

Изменено в версии 3.4: Обновлено: теперь функция основана на PEP 451.

Устарело с версии 3.12, будет удалено в версии 3.14: Вместо этого используйте importlib.util.find_spec().

pkgutil.iter_importers(fullname='')

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

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

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

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

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

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

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

prefix — строка, добавляемая в начало каждого имени модуля в результате.

Примечание

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

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

Рекурсивно возвращает объекты ModuleInfo для всех модулей в 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__ + '.')

Примечание

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.