pkgutil.md

1> **Источник:** https://python-all.ru/3.16/library/pkgutil.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `pkgutil` – Утилита расширения пакетов89**Исходный код:** [Lib/pkgutil.py](https://python-all.ru/src/main/Lib/pkgutil.py)1011---1213Этот модуль предоставляет утилиты для системы импорта, в частности поддержку пакетов.1415#### `class pkgutil.ModuleInfo(module_finder, name, ispkg)`1617Namedtuple, содержащий краткую сводку информации о модуле.1819Добавлено в версии 3.6.2021#### `pkgutil.extend_path(path, name)`2223Расширяет путь поиска модулей, составляющих пакет. Предполагается, что следующий код будет помещён в `__init__.py` пакета:2425```python26from pkgutil import extend_path27__path__ = extend_path(__path__, __name__)28```2930Для каждого каталога из [`sys.path`](https://python-all.ru/3.16/library/sys.html#sys.path), содержащего подкаталог, имя которого совпадает с именем пакета, этот подкаталог добавляется в [`__path__`](https://python-all.ru/3.16/reference/datamodel.html#module.__path__) пакета. Это полезно, если требуется распространять разные части одного логического пакета в виде нескольких каталогов.3132Также выполняется поиск файлов `*.pkg`, начиная с тех, где `*` соответствует аргументу *name*. Эта возможность похожа на файлы `*.pth` (см. модуль [`site`](https://python-all.ru/3.16/library/site.html#module-site) для подробностей), за исключением того, что строки, начинающиеся с `import`, не обрабатываются особым образом. Файл `*.pkg` принимается как есть: помимо пропуска пустых строк и игнорирования комментариев, все записи, найденные в файле `*.pkg`, добавляются в путь, независимо от того, существуют ли они в файловой системе (это особенность).3334Если входной путь не является списком (как в случае замороженных пакетов), он возвращается без изменений. Входной путь не модифицируется; возвращается расширенная копия. Элементы добавляются только в конец этой копии.3536Предполагается, что [`sys.path`](https://python-all.ru/3.16/library/sys.html#sys.path) является последовательностью. Элементы `sys.path`, которые не являются строками, ссылающимися на существующие каталоги, игнорируются. Элементы Unicode в `sys.path`, вызывающие ошибки при использовании в качестве имён файлов, могут привести к возникновению исключения этой функцией (в соответствии с поведением [`os.path.isdir()`](https://python-all.ru/3.16/library/os.path.html#os.path.isdir)).3738#### `pkgutil.get_importer(path_item)`3940Возвращает объект [finder](https://python-all.ru/3.16/glossary.html#term-finder) для указанного *path\_item*.4142Возвращённый объект finder кэшируется в [`sys.path_importer_cache`](https://python-all.ru/3.16/library/sys.html#sys.path_importer_cache), если он был только что создан хуком пути.4344Кэш (или его часть) можно очистить вручную, если требуется повторное сканирование [`sys.path_hooks`](https://python-all.ru/3.16/library/sys.html#sys.path_hooks).4546Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на [`importlib`](https://python-all.ru/3.16/library/importlib.html#module-importlib) вместо использования внутренней эмуляции импорта [**PEP 302**](https://python-all.ru/3.16/library/pkgutil.html) пакета.4748#### `pkgutil.iter_importers(fullname='')`4950Возвращает (как генератор) объекты [finder](https://python-all.ru/3.16/glossary.html#term-finder) для указанного имени модуля.5152Если *fullname* содержит `'.'`, то поисковики будут относиться к пакету, содержащему *fullname*; в противном случае будут возвращены все зарегистрированные поисковики верхнего уровня (то есть те, что находятся в [`sys.meta_path`](https://python-all.ru/3.16/library/sys.html#sys.meta_path) и [`sys.path_hooks`](https://python-all.ru/3.16/library/sys.html#sys.path_hooks)).5354Если указанный модуль находится в пакете, этот пакет импортируется как побочный эффект вызова данной функции.5556Если имя модуля не указано, возвращаются все поисковики верхнего уровня.5758Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на [`importlib`](https://python-all.ru/3.16/library/importlib.html#module-importlib) вместо использования внутренней эмуляции импорта [**PEP 302**](https://python-all.ru/3.16/library/pkgutil.html) пакета.5960#### `pkgutil.iter_modules(path=None, prefix='')`6162Возвращает [`ModuleInfo`](https://python-all.ru/3.16/library/pkgutil.html#pkgutil.ModuleInfo) для всех подмодулей в *path*, или, если *path* равно `None`, все модули верхнего уровня из [`sys.path`](https://python-all.ru/3.16/library/sys.html#sys.path).6364*path* должен быть либо `None`, либо списком путей для поиска модулей.6566*prefix* – это строка, которая выводится перед именем каждого модуля в выводе.6768> **Примечание**69>70> Работает только для [finder](https://python-all.ru/3.16/glossary.html#term-finder), который определяет метод `iter_modules()`. Этот интерфейс нестандартный, поэтому модуль также предоставляет реализации для [`importlib.machinery.FileFinder`](https://python-all.ru/3.16/library/importlib.html#importlib.machinery.FileFinder) и [`zipimport.zipimporter`](https://python-all.ru/3.16/library/zipimport.html#zipimport.zipimporter).7172Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на [`importlib`](https://python-all.ru/3.16/library/importlib.html#module-importlib) вместо использования внутренней эмуляции импорта [**PEP 302**](https://python-all.ru/3.16/library/pkgutil.html) пакета.7374#### `pkgutil.walk_packages(path=None, prefix='', onerror=None)`7576Возвращает [`ModuleInfo`](https://python-all.ru/3.16/library/pkgutil.html#pkgutil.ModuleInfo) для всех модулей рекурсивно в *path*, или, если *path* равно `None`, всех доступных модулей.7778*path* должен быть либо `None`, либо списком путей для поиска модулей.7980*prefix* – это строка, которая выводится перед именем каждого модуля в выводе.8182Обратите внимание, что эта функция должна импортировать все *пакеты* (*не* все модули!) по заданному *пути*, чтобы получить доступ к атрибуту `__path__` для поиска подмодулей.8384*onerror* – это функция, которая вызывается с одним аргументом (именем пакета, который импортировался), если при попытке импортировать пакет возникает исключение. Если функция *onerror* не указана, то [`ImportError`](https://python-all.ru/3.16/library/exceptions.html#ImportError) перехватываются и игнорируются, а все остальные исключения распространяются, прекращая поиск.8586Примеры:8788```python89# вывести все модули, доступные Python90walk_packages()9192# вывести все подмодули ctypes93walk_packages(ctypes.__path__, ctypes.__name__ + '.')94```9596> **Примечание**97>98> Работает только для [finder](https://python-all.ru/3.16/glossary.html#term-finder), который определяет метод `iter_modules()`. Этот интерфейс нестандартный, поэтому модуль также предоставляет реализации для [`importlib.machinery.FileFinder`](https://python-all.ru/3.16/library/importlib.html#importlib.machinery.FileFinder) и [`zipimport.zipimporter`](https://python-all.ru/3.16/library/zipimport.html#zipimport.zipimporter).99100Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на [`importlib`](https://python-all.ru/3.16/library/importlib.html#module-importlib) вместо использования внутренней эмуляции импорта [**PEP 302**](https://python-all.ru/3.16/library/pkgutil.html) пакета.101102#### `pkgutil.get_data(package, resource)`103104Получить ресурс из пакета.105106Это обёртка для API [загрузчика](https://python-all.ru/3.16/glossary.html#term-loader) [`get_data`](https://python-all.ru/3.16/library/importlib.html#importlib.abc.ResourceLoader.get_data). Аргумент *package* должен быть именем пакета в стандартном формате модуля (`foo.bar`). Аргумент *resource* должен быть в виде относительного имени файла, с использованием `/` в качестве разделителя пути.107108Функция возвращает двоичную строку, содержащую указанный ресурс.109110Эта функция использует метод [загрузчика](https://python-all.ru/3.16/glossary.html#term-loader) [`get_data()`](https://python-all.ru/3.16/library/importlib.html#importlib.abc.FileLoader.get_data), чтобы поддерживать модули, установленные в файловой системе, а также в zip-файлах, базах данных или других местах.111112Для пакетов, расположенных в файловой системе, которые уже были импортированы, это приблизительный эквивалент следующего:113114```python115d = os.path.dirname(sys.modules[package].__file__)116data = open(os.path.join(d, resource), 'rb').read()117```118119Как и функция [`open()`](https://python-all.ru/3.16/library/functions.html#open), `get_data()` может переходить по родительским каталогам (`../`) и абсолютным путям (начинающимся с `/` или `C:/`, например). Она может открывать артефакты компиляции/установки, такие как файлы `.py` и `.pyc` или файлы с [`reserved filenames`](https://python-all.ru/3.16/library/os.path.html#os.path.isreserved). Для совместимости с загрузчиками, не основанными на файловой системе, избегайте использования этих возможностей.120121> **Предупреждение**122>123> Эта функция предназначена для доверенных входных данных. Она не проверяет, что *resource* «принадлежит» *package*.124125При использовании предоставленного пользователем пути *resource* рекомендуется его проверять. Например, требовать алфавитно-цифровое имя файла с известным расширением или установить и проверять список известных ресурсов.126127Если пакет не может быть найден или загружен, или используется [загрузчик](https://python-all.ru/3.16/glossary.html#term-loader), не поддерживающий [`get_data`](https://python-all.ru/3.16/library/importlib.html#importlib.abc.ResourceLoader.get_data), то возвращается `None`. В частности, загрузчик для [пространств имён пакетов](https://python-all.ru/3.16/glossary.html#term-namespace-package) не поддерживает `get_data`.128129> **См. также**130>131> Модуль [`importlib.resources`](https://python-all.ru/3.16/library/importlib.resources.html#module-importlib.resources) предоставляет структурированный доступ к ресурсам модулей.132133#### `pkgutil.resolve_name(name, *, strict=False)`134135Разрешить имя в объект.136137Эта функциональность используется во многих местах стандартной библиотеки (см. [bpo-12915](https://python-all.ru/3.16/library/pkgutil.html)) – и эквивалентная функциональность также имеется в широко используемых сторонних пакетах, таких как setuptools, Django и Pyramid.138139Ожидается, что *name* будет строкой в одном из следующих форматов, где W – сокращение для допустимого идентификатора Python, а точка обозначает литеральную точку в этих псевдорегулярных выражениях:140141- `W(.W)*`142- `W(.W)*:(W(.W)*)?`143- `W(.W)*:(W(.W)*)`144145Первая форма предназначена только для обратной совместимости. Она предполагает, что некоторая часть точечного имени является пакетом, а остальное – объект где-то внутри этого пакета, возможно, вложенный в другие объекты. Поскольку место, где заканчивается пакет и начинается иерархия объектов, невозможно определить путём анализа, при использовании этой формы приходится выполнять многократные попытки импорта.146147Во второй форме вызывающий код указывает точку разделения с помощью одного двоеточия: точечное имя слева от двоеточия – это пакет, который нужно импортировать, а точечное имя справа – это иерархия объектов внутри этого пакета. В этой форме требуется только один импорт. Если имя заканчивается двоеточием, возвращается объект модуля.148149Первые две формы принимаются, когда `strict=False` (по умолчанию).150151Третья форма требует и имя модуля, и вызываемый объект, разделённые двоеточием. Только эта форма принимается, когда `strict=True`.152153Функция возвращает объект (который может быть модулем) или возбуждает одно из следующих исключений:154155[`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError) – если *name* не в распознаваемом формате.156157[`ImportError`](https://python-all.ru/3.16/library/exceptions.html#ImportError) – если импорт не удался, хотя не должен был.158159[`AttributeError`](https://python-all.ru/3.16/library/exceptions.html#AttributeError) – если произошла ошибка при обходе иерархии объектов внутри импортированного пакета для достижения нужного объекта.160161Добавлено в версии 3.9.162163Изменено в версии 3.15: Был добавлен необязательный параметр только-по-ключу `strict`.164