pkgutil.md

1> **Источник:** https://python-all.ru/3.1/library/pkgutil.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 29.3. `pkgutil` – Утилита расширения пакетов89Этот модуль предоставляет утилиты для системы импорта, в частности поддержку пакетов.1011#### `pkgutil.extend_path(path, name)`1213Расширяет путь поиска для модулей, из которых состоит пакет. Предполагаемое использование – разместить следующий код в `__init__.py` пакета:1415```python16from pkgutil import extend_path17__path__ = extend_path(__path__, __name__)18```1920Это добавит в `__path__` пакета все подкаталоги каталогов из `sys.path`, названные в честь пакета. Это полезно, если нужно распространять разные части одного логического пакета как несколько каталогов.2122Также ищет файлы `*.pkg`, начиная с того места, где `*` совпадает с аргументом *name*. Эта возможность аналогична файлам `*.pth` (см. модуль [`site`](https://python-all.ru/3.1/library/site.html#module-site) для подробностей), за исключением того, что строки, начинающиеся с `import`, не обрабатываются особым образом. Файл `*.pkg` принимается за чистую монету: помимо проверки на дубликаты, все записи, найденные в файле `*.pkg`, добавляются в путь независимо от того, существуют ли они в файловой системе. (Это особенность.)2324Если входной путь не является списком (как в случае замороженных пакетов), он возвращается без изменений. Входной путь не модифицируется; возвращается расширенная копия. Элементы добавляются только в конец этой копии.2526Предполагается, что [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path) является последовательностью. Элементы [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path), не являющиеся строками, указывающими на существующие каталоги, игнорируются. Элементы Unicode в [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path), которые вызывают ошибки при использовании в качестве имён файлов, могут привести к тому, что эта функция вызовет исключение (в соответствии с поведением [`os.path.isdir()`](https://python-all.ru/3.1/library/os.path.html#os.path.isdir)).2728#### `class pkgutil.ImpImporter(dirname=None)`2930[**PEP 302**](https://python-all.ru/3.1/library/pkgutil.html) Импортёр, который оборачивает «классический» алгоритм импорта Python.3132Если *dirname* – строка, создаётся импортёр [**PEP 302**](https://python-all.ru/3.1/library/pkgutil.html), который выполняет поиск в этом каталоге. Если *dirname* равно `None`, создаётся импортёр [**PEP 302**](https://python-all.ru/3.1/library/pkgutil.html), который выполняет поиск в текущем [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path), а также во всех замороженных или встроенных модулях.3334Обратите внимание, что [`ImpImporter`](https://python-all.ru/3.1/library/pkgutil.html#pkgutil.ImpImporter) в настоящее время не поддерживает использование путём помещения в [`sys.meta_path`](https://python-all.ru/3.1/library/sys.html#sys.meta_path).3536#### `class pkgutil.ImpLoader(fullname, file, filename, etc)`3738[**PEP 302**](https://python-all.ru/3.1/library/pkgutil.html)3940Загрузчик, который оборачивает «классический» алгоритм импорта Python.4142#### `pkgutil.find_loader(fullname)`4344Найти [**PEP 302**](https://python-all.ru/3.1/library/pkgutil.html) объект-загрузчик для *fullname*.4546Если *fullname* содержит точки, то path должен быть `__path__` содержащего пакета. Возвращает `None`, если модуль не найден или не может быть импортирован. Эта функция использует [`iter_importers()`](https://python-all.ru/3.1/library/pkgutil.html#pkgutil.iter_importers) и, следовательно, имеет те же ограничения, что и встроенный механизм импорта, касающиеся платформенно-зависимых специальных расположений импорта, таких как реестр Windows.4748#### `pkgutil.get_importer(path_item)`4950Извлекает импортёр [**PEP 302**](https://python-all.ru/3.1/library/pkgutil.html) для указанного *path\_item*.5152Возвращённый импортёр кэшируется в [`sys.path_importer_cache`](https://python-all.ru/3.1/library/sys.html#sys.path_importer_cache), если он был только что создан хуком пути.5354Если импортер отсутствует, возвращается обертка вокруг базового механизма импорта. Эта обертка никогда не вставляется в кеш импортеров (вместо нее вставляется `None`).5556Кэш (или его часть) можно очистить вручную, если требуется повторное сканирование [`sys.path_hooks`](https://python-all.ru/3.1/library/sys.html#sys.path_hooks).5758#### `pkgutil.get_loader(module_or_name)`5960Получить объект «загрузчик» [**PEP 302**](https://python-all.ru/3.1/library/pkgutil.html) для *module\_or\_name*.6162Если модуль или пакет доступны через обычный механизм импорта, возвращается обёртка соответствующей части этого механизма. Возвращает `None`, если модуль не удаётся найти или импортировать. Если указанный модуль ещё не импортирован, импортируется его содержащий пакет (если он есть), чтобы установить `__path__` пакета.6364Эта функция использует [`iter_importers()`](https://python-all.ru/3.1/library/pkgutil.html#pkgutil.iter_importers), и поэтому имеет те же ограничения в отношении платформенно-зависимых специальных расположений импорта, таких как реестр Windows.6566#### `pkgutil.iter_importers(fullname='')`6768Порождает импортёры [**PEP 302**](https://python-all.ru/3.1/library/pkgutil.html) для указанного имени модуля.6970Если fullname содержит точку, импортеры будут для пакета, содержащего fullname; в противном случае они будут импортерами для [`sys.meta_path`](https://python-all.ru/3.1/library/sys.html#sys.meta_path), [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path) и «классического» механизма импорта Python, в указанном порядке. Если именованный модуль находится в пакете, этот пакет импортируется как побочный эффект вызова данной функции.7172Не подчиняющиеся [**PEP 302**](https://python-all.ru/3.1/library/pkgutil.html) механизмы (например, реестр Windows), используемые стандартным механизмом импорта для поиска файлов в альтернативных расположениях, частично поддерживаются, но поиск осуществляется *после* [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path). Обычно эти расположения проверяются *до* [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path), что предотвращает переопределение их [`записями sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path).7374Для того чтобы это вызвало заметную разницу в поведении, должно существовать имя модуля или пакета, доступное как через [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path), так и через один из не-[**PEP 302**](https://python-all.ru/3.1/library/pkgutil.html) файловых механизмов. В этом случае эмуляция найдет первую версию, а встроенный механизм импорта – вторую.7576Элементы следующих типов могут быть затронуты этим несоответствием: `imp.C_EXTENSION`, `imp.PY_SOURCE`, `imp.PY_COMPILED`, `imp.PKG_DIRECTORY`.7778#### `pkgutil.iter_modules(path=None, prefix='')`7980Возвращает `(module_loader, name, ispkg)` для всех подмодулей на *path*, или, если path равен `None`, для всех модулей верхнего уровня на `sys.path`.8182*path* должен быть либо `None`, либо списком путей для поиска модулей.8384*prefix* – это строка, которая выводится перед именем каждого модуля в выводе.8586#### `pkgutil.walk_packages(path=None, prefix='', onerror=None)`8788Возвращает `(module_loader, name, ispkg)` для всех модулей рекурсивно на *path*, или, если path равен `None`, для всех доступных модулей.8990*path* должен быть либо `None`, либо списком путей для поиска модулей.9192*prefix* – это строка, которая выводится перед именем каждого модуля в выводе.9394Обратите внимание, что эта функция должна импортировать все *пакеты* (*не* все модули!) на заданном *path*, чтобы получить доступ к атрибуту `__path__` для поиска подмодулей.9596*onerror* – это функция, которая вызывается с одним аргументом (имя пакета, который импортировался), если при попытке импорта пакета возникает какое-либо исключение. Если функция *onerror* не указана, то [`ImportError`](https://python-all.ru/3.1/library/exceptions.html#ImportError) перехватываются и игнорируются, а все остальные исключения распространяются дальше, прекращая поиск.9798Примеры:99100```python101# вывести все модули, доступные Python102walk_packages()103104# вывести все подмодули ctypes105walk_packages(ctypes.__path__, ctypes.__name__ + '.')106```107108#### `pkgutil.get_data(package, resource)`109110Получить ресурс из пакета.111112Это обёртка для API [`get_data()`](https://python-all.ru/3.1/library/pkgutil.html#pkgutil.get_data) загрузчика PEP 302. Аргумент package должен быть именем пакета в стандартном формате модуля (foo.bar). Аргумент resource должен быть относительным именем файла, с использованием `/` в качестве разделителя путей. Имя родительского каталога `..` не допускается, равно как и абсолютное имя (начинающееся с `/`).113114Функция возвращает двоичную строку, содержащую указанный ресурс.115116Для пакетов, расположенных в файловой системе, которые уже были импортированы, это приблизительный эквивалент следующего:117118```python119d = os.path.dirname(sys.modules[package].__file__)120data = open(os.path.join(d, resource), 'rb').read()121```122123Если пакет не удаётся найти или загрузить, или используется загрузчик PEP 302, который не поддерживает [`get_data()`](https://python-all.ru/3.1/library/pkgutil.html#pkgutil.get_data), то возвращается `None`.124