29.3. pkgutil – Утилита расширения пакетов¶pkgutil – Package extension utility
Этот модуль предоставляет утилиты для системы импорта, в частности поддержку пакетов.
- 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.
- 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, чтобы получить доступ к атрибуту __path__ для поиска подмодулей.
onerror – это функция, которая вызывается с одним аргументом (имя пакета, который импортировался), если при попытке импорта пакета возникает какое-либо исключение. Если функция onerror не указана, то ImportError перехватываются и игнорируются, а все остальные исключения распространяются дальше, прекращая поиск.
Примеры:
# вывести все модули, доступные Python walk_packages() # вывести все подмодули ctypes walk_packages(ctypes.__path__, ctypes.__name__ + '.')
- pkgutil.get_data(package, resource)¶
Получить ресурс из пакета.
Это обёртка для API get_data() загрузчика PEP 302. Аргумент 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.