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

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

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

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 или 8-битными) строками, ссылающимися на существующие каталоги, игнорируются. Элементы 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.

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

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

pkgutil.find_loader(fullname)¶

Найти PEP 302 объект-загрузчик для fullname.

Если fullname содержит точки, path должен быть содержащего пакета __path__. Возвращает None, если модуль не удалось найти или импортировать. Эта функция использует iter_importers() и, следовательно, подвержена тем же ограничениям в отношении платформенно-зависимых специальных мест импорта, таких как реестр Windows.

pkgutil.get_importer(path_item)¶

Извлекает импортёр PEP 302 для указанного path_item.

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

Если импортер отсутствует, возвращается обертка вокруг базового механизма импорта. Эта обертка никогда не вставляется в кэш импортеров (вместо нее вставляется None).

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

pkgutil.get_loader(module_or_name)¶

Получить объект «загрузчик» PEP 302 для module_or_name.

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

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

pkgutil.iter_importers(fullname='')¶

Порождает импортёры PEP 302 для указанного имени модуля.

Если fullname содержит точку, импортеры будут для пакета, содержащего fullname; в противном случае они будут импортерами для sys.meta_path, sys.path и «классического» механизма импорта Python, в указанном порядке. Если именованный модуль находится в пакете, этот пакет импортируется как побочный эффект вызова данной функции.

Механизмы, не являющиеся PEP 302 (например, реестр Windows), используемые стандартным механизмом импорта для поиска файлов в альтернативных местах, частично поддерживаются, но поиск по ним выполняется после sys.path. Обычно эти места просматриваются до sys.path, предотвращая sys.path скрытие их записями.

Чтобы это привело к заметной разнице в поведении, необходимо, чтобы имя модуля или пакета было доступно как через sys.path, так и через один из не-PEP 302 файловых механизмов. В этом случае эмуляция найдет первую версию, а встроенный механизм импорта – вторую.

Элементы следующих типов могут быть затронуты этим несоответствием: imp.C_EXTENSION, imp.PY_SOURCE, imp.PY_COMPILED, imp.PKG_DIRECTORY.

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

Генерирует (module_loader, name, ispkg) для всех подмодулей в path, или, если path равно None, все модули верхнего уровня на sys.path.

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

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

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

Генерирует (module_loader, name, ispkg) для всех модулей рекурсивно на 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 PEP 302 загрузчика get_data(). Аргумент package должен быть именем пакета в стандартном формате модуля (foo.bar). Аргумент resource должен быть в форме относительного имени файла с использованием / в качестве разделителя путей. Имя родительского каталога .. не допускается, как и имя с корнем (начинающееся с /).

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

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

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

Если пакет не удалось найти или загрузить, или он использует загрузчик PEP 302, который не поддерживает get_data(), то возвращается None.

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