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.get_importer(path_item)

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

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

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

Изменено в версии 3.3: Обновлено: теперь функция непосредственно основана на importlib, а не на эмуляции импорта, встроенной в пакет и основанной на PEP 302.

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 должен иметь вид относительного имени файла, где в качестве разделителя пути используется /.

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

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

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

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

Как и функция open(), get_data() может обращаться к родительским каталогам (../) и абсолютным путям (например, начинающимся с / или C:/). Она может открывать артефакты компиляции или установки, например файлы .py и .pyc, а также файлы, для которых reserved filenames. Для совместимости с загрузчиками, не использующими файловую систему, избегайте этих возможностей.

Предупреждение

Эта функция предназначена для доверенных данных. Она не проверяет, «принадлежит» ли resource пакету package.

Если вы используете путь resource, предоставленный пользователем, рассмотрите возможность его проверки. Например, потребуйте имя файла, состоящее из букв и цифр и имеющее известное расширение, либо установите и проверьте список известных ресурсов.

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

См. также

Модуль importlib.resources предоставляет структурированный доступ к ресурсам модулей.

pkgutil.resolve_name(name)

Разрешает имя в объект.

Эта функциональность используется во многих местах стандартной библиотеки (см. bpo-12915); аналогичная функциональность есть и в широко используемых сторонних пакетах, таких как setuptools, Django и Pyramid.

Предполагается, что name — это строка одного из следующих форматов, где W — сокращённое обозначение допустимого идентификатора Python, а точка означает буквальную точку в этих псевдорегулярных выражениях:

W(.W)*
W(.W)*:(W(.W)*)?

Первая форма предназначена только для обратной совместимости. Она предполагает, что некоторая часть имени с точками является пакетом, а остальная часть — объектом в этом пакете, возможно вложенным в другие объекты. Поскольку невозможно определить по строке, где заканчивается пакет и начинается иерархия объектов, при использовании этой формы необходимо многократно выполнять попытки импорта.

Во второй форме вызывающий код явно указывает точку разделения с помощью двоеточия: имя с точками слева от двоеточия — это импортируемый пакет, а имя с точками справа — иерархия объектов внутри этого пакета. При использовании этой формы требуется только один импорт. Если строка заканчивается двоеточием, возвращается объект модуля.

Функция возвращает объект (который может быть модулем) или вызывает одно из следующих исключений:

ValueError — если name имеет неизвестный формат.

ImportError — если импорт завершился с ошибкой, хотя этого не должно было произойти.

AttributeError — если при обходе иерархии объектов внутри импортированного пакета для получения нужного объекта произошла ошибка.

Добавлено в версии 3.9.