31.2. `pkgutil` – Утилита расширения пакетов¶pkgutil – Package extension utility

Исходный код: Lib/pkgutil.py

Этот модуль предоставляет утилиты для системы импорта, в частности поддержку пакетов.

pkgutil.extend_path(path, name)¶

Расширяет путь поиска для модулей, из которых состоит пакет. Предполагаемое использование – разместить следующий код в __init__.py пакета:

from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

Это добавит в __path__ пакета все подкаталоги каталогов из sys.path, названные в честь пакета. Это полезно, если нужно распространять разные части одного логического пакета как несколько каталогов.

Также ищет файлы *.pkg, начиная с того места, где * совпадает с аргументом name. Эта возможность аналогична файлам *.pth (см. модуль site для подробностей), за исключением того, что строки, начинающиеся с import, не обрабатываются особым образом. Файл *.pkg принимается за чистую монету: помимо проверки на дубликаты, все записи, найденные в файле *.pkg, добавляются в путь независимо от того, существуют ли они в файловой системе. (Это особенность.)

Если входной путь не является списком (как в случае замороженных пакетов), он возвращается без изменений. Входной путь не модифицируется; возвращается расширенная копия. Элементы добавляются только в конец этой копии.

Предполагается, что sys.path является последовательностью. Элементы sys.path, не являющиеся строками, указывающими на существующие каталоги, игнорируются. Элементы Unicode в sys.path, которые вызывают ошибки при использовании в качестве имён файлов, могут привести к тому, что эта функция вызовет исключение (в соответствии с поведением os.path.isdir()).

class pkgutil.ImpImporter(dirname=None)¶

PEP 302 Импортёр, который оборачивает «классический» алгоритм импорта Python.

Если dirname – строка, создаётся импортёр PEP 302, который выполняет поиск в этом каталоге. Если dirname равно None, создаётся импортёр PEP 302, который выполняет поиск в текущем sys.path, а также во всех замороженных или встроенных модулях.

Обратите внимание, что ImpImporter в настоящее время не поддерживает использование путём помещения в sys.meta_path.

Устарело с версии 3.3: Эта эмуляция больше не нужна, поскольку стандартный механизм импорта теперь полностью соответствует PEP 302 и доступен в importlib

class pkgutil.ImpLoader(fullname, file, filename, etc)¶: PEP 302 Загрузчик, который оборачивает «классический» алгоритм импорта Python.

Устарело с версии 3.3: Эта эмуляция больше не нужна, поскольку стандартный механизм импорта теперь полностью соответствует PEP 302 и доступен в importlib

pkgutil.find_loader(fullname)¶

Извлекает загрузчик модуля PEP 302 для указанного fullname.

Это обёртка обратной совместимости вокруг importlib.util.find_spec(), которая преобразует большинство ошибок в ImportError и возвращает только загрузчик, а не полный ModuleSpec.

Изменено в версии 3.3: Обновлено для прямой привязки к importlib вместо использования внутренней эмуляции импорта PEP 302 пакета.

Изменено в версии 3.4: Обновлено для использования на основе PEP 451

pkgutil.get_importer(path_item)¶

Извлекает импортёр PEP 302 для указанного path_item.

Возвращённый импортёр кэшируется в sys.path_importer_cache, если он был только что создан хуком пути.

Кэш (или его часть) можно очистить вручную, если требуется повторное сканирование sys.path_hooks.

pkgutil.get_loader(module_or_name)¶

Получить объект «загрузчик» PEP 302 для module_or_name.

Если модуль или пакет доступны через обычный механизм импорта, возвращается обёртка соответствующей части этого механизма. Возвращает None, если модуль не удаётся найти или импортировать. Если указанный модуль ещё не импортирован, импортируется его содержащий пакет (если он есть), чтобы установить __path__ пакета.

Изменено в версии 3.4: Обновлено для использования на основе PEP 451

pkgutil.iter_importers(fullname='')¶

Порождает импортёры PEP 302 для указанного имени модуля.

Если fullname содержит точку, импортёры будут для пакета, содержащего fullname; в противном случае это будут все зарегистрированные импортёры верхнего уровня (т.е. те, что находятся как в sys.meta_path, так и в sys.path_hooks).

Если указанный модуль находится в пакете, этот пакет импортируется как побочный эффект вызова данной функции.

Если имя модуля не указано, порождаются все импортёры верхнего уровня.

Изменено в версии 3.3: Теперь напрямую использует importlib вместо внутренней эмуляции импорта PEP 302.

pkgutil.iter_modules(path=None, prefix='')¶

Возвращает (module_finder, name, ispkg) для всех подмодулей на path, или, если path равен None, все модули верхнего уровня на sys.path.

path должен быть либо None, либо списком путей для поиска модулей.

prefix – это строка, которая выводится перед именем каждого модуля в выводе.

Примечание

Работает только для finder, который определяет метод iter_modules(). Этот интерфейс нестандартен, поэтому модуль также предоставляет реализации для importlib.machinery.FileFinder и zipimport.zipimporter.

Изменено в версии 3.3: Теперь напрямую использует 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 перехватываются и игнорируются, а все остальные исключения распространяются дальше, прекращая поиск.

Примеры:

# вывести все модули, доступные Python
walk_packages()

# вывести все подмодули ctypes
walk_packages(ctypes.__path__, ctypes.__name__ + '.')

Примечание

Изменено в версии 3.3: Теперь напрямую использует importlib вместо внутренней эмуляции импорта PEP 302.

pkgutil.get_data(package, resource)¶

Получить ресурс из пакета.

Это обёртка для PEP 302 загрузчика get_data() API. Аргумент package должен быть именем пакета в стандартном формате модуля (foo.bar). Аргумент resource должен быть в виде относительного имени файла, с использованием / в качестве разделителя путей. Имя родительского каталога .. не допускается, равно как и абсолютное имя (начинающееся с /).

Функция возвращает двоичную строку, содержащую указанный ресурс.

Для пакетов, расположенных в файловой системе, которые уже были импортированы, это приблизительный эквивалент следующего:

d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()

Если пакет не удаётся найти или загрузить, или он использует PEP 302 загрузчик, который не поддерживает get_data(), то возвращается None.

31.2. pkgutil – Утилита расширения пакетов¶pkgutil – Package extension utility

31.2. `pkgutil` – Утилита расширения пакетов¶pkgutil – Package extension utility