pkgutil.md

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