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

Исходный код: 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 содержит точки, путь должен быть каталогом содержащего пакета. Возвращает 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 игнорируются, а все остальные исключения распространяются, завершая поиск.

Примеры:

# 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 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.