> **Источник:** https://python-all.ru/3.10/library/pkgutil.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # [`pkgutil`](https://python-all.ru/3.10/library/pkgutil.html#module-pkgutil) – Утилита расширения пакетов **Исходный код:** [Lib/pkgutil.py](https://python-all.ru/src/3.10/Lib/pkgutil.py) --- Этот модуль предоставляет утилиты для системы импорта, в частности поддержку пакетов. #### `class pkgutil.ModuleInfo(module_finder, name, ispkg)` Namedtuple, содержащий краткую сводку информации о модуле. Новое в версии 3.6. #### `pkgutil.extend_path(path, name)` Расширяет путь поиска модулей, составляющих пакет. Предполагается, что следующий код будет помещён в `__init__.py` пакета: ```python from pkgutil import extend_path __path__ = extend_path(__path__, __name__) ``` Это добавит в `__path__` пакета все подкаталоги каталогов из [`sys.path`](https://python-all.ru/3.10/library/sys.html#sys.path), названные по имени пакета. Это полезно, если требуется распространять разные части одного логического пакета как несколько каталогов. Он также ищет файлы `*.pkg`, начиная с тех, где `*` соответствует аргументу *name*. Эта возможность аналогична файлам `*.pth` (см. модуль [`site`](https://python-all.ru/3.10/library/site.html#module-site) для получения дополнительной информации), за исключением того, что строки, начинающиеся с `import`, не обрабатываются особым образом. Файл `*.pkg` принимается без проверки: помимо проверки на дубликаты, все записи, найденные в файле `*.pkg`, добавляются в путь независимо от того, существуют ли они в файловой системе. (Это особенность.) Если входной путь не является списком (как в случае замороженных пакетов), он возвращается без изменений. Входной путь не модифицируется; возвращается расширенная копия. Элементы добавляются только в конец этой копии. Предполагается, что [`sys.path`](https://python-all.ru/3.10/library/sys.html#sys.path) является последовательностью. Элементы [`sys.path`](https://python-all.ru/3.10/library/sys.html#sys.path), которые не являются строками, ссылающимися на существующие каталоги, игнорируются. Элементы Unicode в [`sys.path`](https://python-all.ru/3.10/library/sys.html#sys.path), вызывающие ошибки при использовании в качестве имён файлов, могут привести к возникновению исключения этой функцией (в соответствии с поведением [`os.path.isdir()`](https://python-all.ru/3.10/library/os.path.html#os.path.isdir)). #### `class pkgutil.ImpImporter(dirname=None)` [**PEP 302**](https://python-all.ru/3.10/library/pkgutil.html) поисковик, оборачивающий «классический» алгоритм импорта Python. Если *dirname* является строкой, создаётся [**PEP 302**](https://python-all.ru/3.10/library/pkgutil.html) поисковик, который выполняет поиск в этом каталоге. Если *dirname* равен `None`, создаётся [**PEP 302**](https://python-all.ru/3.10/library/pkgutil.html) поисковик, который ищет в текущем [`sys.path`](https://python-all.ru/3.10/library/sys.html#sys.path), а также в любых замороженных или встроенных модулях. Обратите внимание, что [`ImpImporter`](https://python-all.ru/3.10/library/pkgutil.html#pkgutil.ImpImporter) в настоящее время не поддерживает использование путём размещения на [`sys.meta_path`](https://python-all.ru/3.10/library/sys.html#sys.meta_path). Deprecated since version 3.3: This emulation is no longer needed, as the standard import mechanism is now fully [**PEP 302**](https://python-all.ru/3.10/library/pkgutil.html) compliant and available in [`importlib`](https://python-all.ru/3.10/library/importlib.html#module-importlib). #### `class pkgutil.ImpLoader(fullname, file, filename, etc)` [Loader](https://python-all.ru/3.10/glossary.html#term-loader) оборачивающий «классический» алгоритм импорта Python. Deprecated since version 3.3: This emulation is no longer needed, as the standard import mechanism is now fully [**PEP 302**](https://python-all.ru/3.10/library/pkgutil.html) compliant and available in [`importlib`](https://python-all.ru/3.10/library/importlib.html#module-importlib). #### `pkgutil.find_loader(fullname)` Возвращает загрузчик модуля [loader](https://python-all.ru/3.10/glossary.html#term-loader) для указанного *fullname*. Это обёртка обратной совместимости для [`importlib.util.find_spec()`](https://python-all.ru/3.10/library/importlib.html#importlib.util.find_spec), которая преобразует большинство ошибок в [`ImportError`](https://python-all.ru/3.10/library/exceptions.html#ImportError) и возвращает только загрузчик, а не полный `ModuleSpec`. Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на [`importlib`](https://python-all.ru/3.10/library/importlib.html#module-importlib) вместо использования внутренней эмуляции импорта [**PEP 302**](https://python-all.ru/3.10/library/pkgutil.html) пакета. Изменено в версии 3.4: Обновлено для использования на основе [**PEP 451**](https://python-all.ru/3.10/library/pkgutil.html) #### `pkgutil.get_importer(path_item)` Возвращает объект [finder](https://python-all.ru/3.10/glossary.html#term-finder) для указанного *path\_item*. Возвращённый объект finder кэшируется в [`sys.path_importer_cache`](https://python-all.ru/3.10/library/sys.html#sys.path_importer_cache), если он был только что создан хуком пути. Кэш (или его часть) можно очистить вручную, если требуется повторное сканирование [`sys.path_hooks`](https://python-all.ru/3.10/library/sys.html#sys.path_hooks). Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на [`importlib`](https://python-all.ru/3.10/library/importlib.html#module-importlib) вместо использования внутренней эмуляции импорта [**PEP 302**](https://python-all.ru/3.10/library/pkgutil.html) пакета. #### `pkgutil.get_loader(module_or_name)` Возвращает объект [загрузчика](https://python-all.ru/3.10/glossary.html#term-loader) для *module\_or\_name*. Если модуль или пакет доступен через обычный механизм импорта, возвращается обёртка вокруг соответствующей части этого механизма. Возвращает `None`, если модуль не найден или не может быть импортирован. Если указанный модуль ещё не импортирован, импортируется его содержащий пакет (если есть), чтобы установить `__path__` пакета. Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на [`importlib`](https://python-all.ru/3.10/library/importlib.html#module-importlib) вместо использования внутренней эмуляции импорта [**PEP 302**](https://python-all.ru/3.10/library/pkgutil.html) пакета. Изменено в версии 3.4: Обновлено для использования на основе [**PEP 451**](https://python-all.ru/3.10/library/pkgutil.html) #### `pkgutil.iter_importers(fullname='')` Возвращает (как генератор) объекты [finder](https://python-all.ru/3.10/glossary.html#term-finder) для указанного имени модуля. Если `'.'` присутствует в fullname, то искатели будут для пакета, содержащего fullname; в противном случае возвращаются все зарегистрированные искатели верхнего уровня (то есть те, что находятся как в [`sys.meta_path`](https://python-all.ru/3.10/library/sys.html#sys.meta_path), так и в [`sys.path_hooks`](https://python-all.ru/3.10/library/sys.html#sys.path_hooks)). Если указанный модуль находится в пакете, этот пакет импортируется как побочный эффект вызова данной функции. Если имя модуля не указано, возвращаются все поисковики верхнего уровня. Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на [`importlib`](https://python-all.ru/3.10/library/importlib.html#module-importlib) вместо использования внутренней эмуляции импорта [**PEP 302**](https://python-all.ru/3.10/library/pkgutil.html) пакета. #### `pkgutil.iter_modules(path=None, prefix='')` Возвращает [`ModuleInfo`](https://python-all.ru/3.10/library/pkgutil.html#pkgutil.ModuleInfo) для всех подмодулей в *path*, или, если *path* равно `None`, все модули верхнего уровня из [`sys.path`](https://python-all.ru/3.10/library/sys.html#sys.path). *path* должен быть либо `None`, либо списком путей для поиска модулей. *prefix* – это строка, которая выводится перед именем каждого модуля в выводе. > **Примечание** > > Работает только для [finder](https://python-all.ru/3.10/glossary.html#term-finder), который определяет метод `iter_modules()`. Этот интерфейс нестандартный, поэтому модуль также предоставляет реализации для [`importlib.machinery.FileFinder`](https://python-all.ru/3.10/library/importlib.html#importlib.machinery.FileFinder) и [`zipimport.zipimporter`](https://python-all.ru/3.10/library/zipimport.html#zipimport.zipimporter). Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на [`importlib`](https://python-all.ru/3.10/library/importlib.html#module-importlib) вместо использования внутренней эмуляции импорта [**PEP 302**](https://python-all.ru/3.10/library/pkgutil.html) пакета. #### `pkgutil.walk_packages(path=None, prefix='', onerror=None)` Возвращает [`ModuleInfo`](https://python-all.ru/3.10/library/pkgutil.html#pkgutil.ModuleInfo) для всех модулей рекурсивно в *path*, или, если *path* равно `None`, всех доступных модулей. *path* должен быть либо `None`, либо списком путей для поиска модулей. *prefix* – это строка, которая выводится перед именем каждого модуля в выводе. Обратите внимание, что эта функция должна импортировать все *пакеты* (*не* все модули!) по заданному *пути*, чтобы получить доступ к атрибуту `__path__` для поиска подмодулей. *onerror* – это функция, которая вызывается с одним аргументом (именем пакета, который импортировался), если при попытке импортировать пакет возникает исключение. Если функция *onerror* не указана, то [`ImportError`](https://python-all.ru/3.10/library/exceptions.html#ImportError) перехватываются и игнорируются, а все остальные исключения распространяются, прекращая поиск. Примеры: ```python # вывести все модули, доступные Python walk_packages() # вывести все подмодули ctypes walk_packages(ctypes.__path__, ctypes.__name__ + '.') ``` > **Примечание** > > Работает только для [finder](https://python-all.ru/3.10/glossary.html#term-finder), который определяет метод `iter_modules()`. Этот интерфейс нестандартный, поэтому модуль также предоставляет реализации для [`importlib.machinery.FileFinder`](https://python-all.ru/3.10/library/importlib.html#importlib.machinery.FileFinder) и [`zipimport.zipimporter`](https://python-all.ru/3.10/library/zipimport.html#zipimport.zipimporter). Изменено в версии 3.3: Обновлено, чтобы основываться непосредственно на [`importlib`](https://python-all.ru/3.10/library/importlib.html#module-importlib) вместо использования внутренней эмуляции импорта [**PEP 302**](https://python-all.ru/3.10/library/pkgutil.html) пакета. #### `pkgutil.get_data(package, resource)` Получить ресурс из пакета. Это обёртка для API [загрузчика](https://python-all.ru/3.10/glossary.html#term-loader) [`get_data`](https://python-all.ru/3.10/library/importlib.html#importlib.abc.ResourceLoader.get_data). Аргумент *package* должен быть именем пакета в стандартном формате модуля (`foo.bar`). Аргумент *resource* должен быть задан в виде относительного имени файла с использованием `/` в качестве разделителя путей. Имя родительского каталога `..` не допускается, так же как и имя с корнем (начинающееся с `/`). Функция возвращает двоичную строку, содержащую указанный ресурс. Для пакетов, расположенных в файловой системе, которые уже были импортированы, это приблизительный эквивалент следующего: ```python d = os.path.dirname(sys.modules[package].__file__) data = open(os.path.join(d, resource), 'rb').read() ``` Если пакет не удаётся найти или загрузить, или же он использует [загрузчик](https://python-all.ru/3.10/glossary.html#term-loader), который не поддерживает [`get_data`](https://python-all.ru/3.10/library/importlib.html#importlib.abc.ResourceLoader.get_data), то возвращается `None`. В частности, [загрузчик](https://python-all.ru/3.10/glossary.html#term-loader) для [пакетов пространств имён](https://python-all.ru/3.10/glossary.html#term-namespace-package) не поддерживает [`get_data`](https://python-all.ru/3.10/library/importlib.html#importlib.abc.ResourceLoader.get_data). #### `pkgutil.resolve_name(name)` Разрешить имя в объект. Эта функциональность используется во многих местах стандартной библиотеки (см. [bpo-12915](https://python-all.ru/3.10/library/pkgutil.html)) – и эквивалентная функциональность также имеется в широко используемых сторонних пакетах, таких как setuptools, Django и Pyramid. Ожидается, что *name* будет строкой в одном из следующих форматов, где W – сокращение для допустимого идентификатора Python, а точка обозначает литеральную точку в этих псевдорегулярных выражениях: - `W(.W)*` - `W(.W)*:(W(.W)*)?` Первая форма предназначена только для обратной совместимости. Она предполагает, что некоторая часть точечного имени является пакетом, а остальное – объект где-то внутри этого пакета, возможно, вложенный в другие объекты. Поскольку место, где заканчивается пакет и начинается иерархия объектов, невозможно определить путём анализа, при использовании этой формы приходится выполнять многократные попытки импорта. Во второй форме вызывающий код указывает точку разделения с помощью одного двоеточия: точечное имя слева от двоеточия – это пакет, который нужно импортировать, а точечное имя справа – это иерархия объектов внутри этого пакета. В этой форме требуется только один импорт. Если имя заканчивается двоеточием, возвращается объект модуля. Функция возвращает объект (который может быть модулем) или возбуждает одно из следующих исключений: [`ValueError`](https://python-all.ru/3.10/library/exceptions.html#ValueError) – если *name* не в распознаваемом формате. [`ImportError`](https://python-all.ru/3.10/library/exceptions.html#ImportError) – если импорт не удался, хотя не должен был. [`AttributeError`](https://python-all.ru/3.10/library/exceptions.html#AttributeError) – если произошла ошибка при обходе иерархии объектов внутри импортированного пакета для достижения нужного объекта. Новое в версии 3.9.