> **Источник:** https://python-all.ru/3.3/library/pkgutil.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # 30.3. [`pkgutil`](https://python-all.ru/3.3/library/pkgutil.html#module-pkgutil) – Утилита расширения пакетов **Исходный код:** [Lib/pkgutil.py](https://python-all.ru/src/3.3/Lib/pkgutil.py) --- Этот модуль предоставляет утилиты для системы импорта, в частности поддержку пакетов. #### `pkgutil.extend_path(path, name)` Расширяет путь поиска для модулей, из которых состоит пакет. Предполагаемое использование – разместить следующий код в `__init__.py` пакета: ```python from pkgutil import extend_path __path__ = extend_path(__path__, __name__) ``` Это добавит в `__path__` пакета все подкаталоги каталогов из `sys.path`, названные в честь пакета. Это полезно, если нужно распространять разные части одного логического пакета как несколько каталогов. Также ищет файлы `*.pkg`, начиная с того места, где `*` совпадает с аргументом *name*. Эта возможность аналогична файлам `*.pth` (см. модуль [`site`](https://python-all.ru/3.3/library/site.html#module-site) для подробностей), за исключением того, что строки, начинающиеся с `import`, не обрабатываются особым образом. Файл `*.pkg` принимается за чистую монету: помимо проверки на дубликаты, все записи, найденные в файле `*.pkg`, добавляются в путь независимо от того, существуют ли они в файловой системе. (Это особенность.) Если входной путь не является списком (как в случае замороженных пакетов), он возвращается без изменений. Входной путь не модифицируется; возвращается расширенная копия. Элементы добавляются только в конец этой копии. Предполагается, что [`sys.path`](https://python-all.ru/3.3/library/sys.html#sys.path) является последовательностью. Элементы [`sys.path`](https://python-all.ru/3.3/library/sys.html#sys.path), не являющиеся строками, указывающими на существующие каталоги, игнорируются. Элементы Unicode в [`sys.path`](https://python-all.ru/3.3/library/sys.html#sys.path), которые вызывают ошибки при использовании в качестве имён файлов, могут привести к тому, что эта функция вызовет исключение (в соответствии с поведением [`os.path.isdir()`](https://python-all.ru/3.3/library/os.path.html#os.path.isdir)). #### `class pkgutil.ImpImporter(dirname=None)` [**PEP 302**](https://python-all.ru/3.3/library/pkgutil.html) Импортёр, который оборачивает «классический» алгоритм импорта Python. Если *dirname* – строка, создаётся импортёр [**PEP 302**](https://python-all.ru/3.3/library/pkgutil.html), который выполняет поиск в этом каталоге. Если *dirname* равно `None`, создаётся импортёр [**PEP 302**](https://python-all.ru/3.3/library/pkgutil.html), который выполняет поиск в текущем [`sys.path`](https://python-all.ru/3.3/library/sys.html#sys.path), а также во всех замороженных или встроенных модулях. Обратите внимание, что [`ImpImporter`](https://python-all.ru/3.3/library/pkgutil.html#pkgutil.ImpImporter) в настоящее время не поддерживает использование путём помещения в [`sys.meta_path`](https://python-all.ru/3.3/library/sys.html#sys.meta_path). Устарело с версии 3.3: Эта эмуляция больше не нужна, поскольку стандартный механизм импорта теперь полностью соответствует PEP 302 и доступен в [`importlib`](https://python-all.ru/3.3/library/importlib.html#module-importlib) #### `class pkgutil.ImpLoader(fullname, file, filename, etc)` [**PEP 302**](https://python-all.ru/3.3/library/pkgutil.html) Загрузчик, который оборачивает «классический» алгоритм импорта Python. Устарело с версии 3.3: Эта эмуляция больше не нужна, поскольку стандартный механизм импорта теперь полностью соответствует PEP 302 и доступен в [`importlib`](https://python-all.ru/3.3/library/importlib.html#module-importlib) #### `pkgutil.find_loader(fullname)` Извлекает загрузчик модуля [**PEP 302**](https://python-all.ru/3.3/library/pkgutil.html) для указанного *fullname*. Это удобная обёртка вокруг [`importlib.find_loader()`](https://python-all.ru/3.3/library/importlib.html#importlib.find_loader), которая правильно задаёт аргумент *path* при поиске подмодулей, а также гарантирует, что родительские пакеты (если они есть) импортированы перед поиском подмодулей. Изменено в версии 3.3: Теперь напрямую использует [`importlib`](https://python-all.ru/3.3/library/importlib.html#module-importlib) вместо внутренней эмуляции импорта PEP 302. #### `pkgutil.get_importer(path_item)` Извлекает импортёр [**PEP 302**](https://python-all.ru/3.3/library/pkgutil.html) для указанного *path\_item*. Возвращённый импортёр кэшируется в [`sys.path_importer_cache`](https://python-all.ru/3.3/library/sys.html#sys.path_importer_cache), если он был только что создан хуком пути. Кэш (или его часть) можно очистить вручную, если требуется повторное сканирование [`sys.path_hooks`](https://python-all.ru/3.3/library/sys.html#sys.path_hooks). Изменено в версии 3.3: Теперь напрямую использует [`importlib`](https://python-all.ru/3.3/library/importlib.html#module-importlib) вместо внутренней эмуляции импорта PEP 302. #### `pkgutil.get_loader(module_or_name)` Получить объект «загрузчик» [**PEP 302**](https://python-all.ru/3.3/library/pkgutil.html) для *module\_or\_name*. Если модуль или пакет доступны через обычный механизм импорта, возвращается обёртка соответствующей части этого механизма. Возвращает `None`, если модуль не удаётся найти или импортировать. Если указанный модуль ещё не импортирован, импортируется его содержащий пакет (если он есть), чтобы установить `__path__` пакета. Эта функция использует [`iter_importers()`](https://python-all.ru/3.3/library/pkgutil.html#pkgutil.iter_importers), и поэтому имеет те же ограничения в отношении платформенно-зависимых специальных расположений импорта, таких как реестр Windows. Изменено в версии 3.3: Теперь напрямую использует [`importlib`](https://python-all.ru/3.3/library/importlib.html#module-importlib) вместо внутренней эмуляции импорта PEP 302. #### `pkgutil.iter_importers(fullname='')` Порождает импортёры [**PEP 302**](https://python-all.ru/3.3/library/pkgutil.html) для указанного имени модуля. Если fullname содержит точку, импортёры будут для пакета, содержащего fullname; в противном случае это будут все зарегистрированные импортёры верхнего уровня (т.е. те, что находятся как в sys.meta\_path, так и в sys.path\_hooks). Если указанный модуль находится в пакете, этот пакет импортируется как побочный эффект вызова данной функции. Если имя модуля не указано, порождаются все импортёры верхнего уровня. Изменено в версии 3.3: Теперь напрямую использует [`importlib`](https://python-all.ru/3.3/library/importlib.html#module-importlib) вместо внутренней эмуляции импорта PEP 302. #### `pkgutil.iter_modules(path=None, prefix='')` Возвращает `(module_finder, name, ispkg)` для всех подмодулей на *path*, или, если path равен `None`, все модули верхнего уровня на `sys.path`. *path* должен быть либо `None`, либо списком путей для поиска модулей. *prefix* – это строка, которая выводится перед именем каждого модуля в выводе. > **Примечание** > > Работает только для [*finder*](https://python-all.ru/3.3/glossary.html#term-finder), который определяет метод `iter_modules()`. Этот интерфейс нестандартен, поэтому модуль также предоставляет реализации для [`importlib.machinery.FileFinder`](https://python-all.ru/3.3/library/importlib.html#importlib.machinery.FileFinder) и [`zipimport.zipimporter`](https://python-all.ru/3.3/library/zipimport.html#zipimport.zipimporter). Изменено в версии 3.3: Теперь напрямую использует [`importlib`](https://python-all.ru/3.3/library/importlib.html#module-importlib) вместо внутренней эмуляции импорта PEP 302. #### `pkgutil.walk_packages(path=None, prefix='', onerror=None)` Возвращает `(module_finder, name, ispkg)` для всех модулей рекурсивно на *path*, или, если path равен `None`, все доступные модули. *path* должен быть либо `None`, либо списком путей для поиска модулей. *prefix* – это строка, которая выводится перед именем каждого модуля в выводе. Обратите внимание, что эта функция должна импортировать все *пакеты* (*не* все модули!) на заданном *path*, чтобы получить доступ к атрибуту `__path__` для поиска подмодулей. *onerror* – это функция, которая вызывается с одним аргументом (имя пакета, который импортировался), если при попытке импорта пакета возникает какое-либо исключение. Если функция *onerror* не указана, то [`ImportError`](https://python-all.ru/3.3/library/exceptions.html#ImportError) перехватываются и игнорируются, а все остальные исключения распространяются дальше, прекращая поиск. Примеры: ```python # вывести все модули, доступные Python walk_packages() # вывести все подмодули ctypes walk_packages(ctypes.__path__, ctypes.__name__ + '.') ``` > **Примечание** > > Работает только для [*finder*](https://python-all.ru/3.3/glossary.html#term-finder), который определяет метод `iter_modules()`. Этот интерфейс нестандартен, поэтому модуль также предоставляет реализации для [`importlib.machinery.FileFinder`](https://python-all.ru/3.3/library/importlib.html#importlib.machinery.FileFinder) и [`zipimport.zipimporter`](https://python-all.ru/3.3/library/zipimport.html#zipimport.zipimporter). Изменено в версии 3.3: Теперь напрямую использует [`importlib`](https://python-all.ru/3.3/library/importlib.html#module-importlib) вместо внутренней эмуляции импорта PEP 302. #### `pkgutil.get_data(package, resource)` Получить ресурс из пакета. Это обёртка для [**PEP 302**](https://python-all.ru/3.3/library/pkgutil.html) загрузчика [`get_data()`](https://python-all.ru/3.3/library/pkgutil.html#pkgutil.get_data) API. Аргумент *package* должен быть именем пакета в стандартном формате модуля (`foo.bar`). Аргумент *resource* должен быть в виде относительного имени файла, с использованием `/` в качестве разделителя путей. Имя родительского каталога `..` не допускается, равно как и абсолютное имя (начинающееся с `/`). Функция возвращает двоичную строку, содержащую указанный ресурс. Для пакетов, расположенных в файловой системе, которые уже были импортированы, это приблизительный эквивалент следующего: ```python d = os.path.dirname(sys.modules[package].__file__) data = open(os.path.join(d, resource), 'rb').read() ``` Если пакет не удаётся найти или загрузить, или он использует [**PEP 302**](https://python-all.ru/3.3/library/pkgutil.html) загрузчик, который не поддерживает [`get_data()`](https://python-all.ru/3.3/library/pkgutil.html#pkgutil.get_data), то возвращается `None`.