Документация Python неофициальный перевод
Содержание страницы

importlib.resources – чтение, открытие и доступ к ресурсам пакетовimportlib.resources – Package resource reading, opening and access

Исходный код: Lib/importlib/resources/__init__.py

Добавлено в версии 3.7.

Этот модуль использует систему импорта Python для обеспечения доступа к ресурсам внутри пакетов.

«Ресурсы» – это файлоподобные ресурсы, связанные с модулем или пакетом в Python. Ресурсы могут находиться непосредственно в пакете, в подкаталоге этого пакета или рядом с модулями вне пакета. Ресурсы могут быть текстовыми или двоичными. Как следствие, исходные файлы модулей Python (.py), артефакты компиляции (pycache) и артефакты установки (например, reserved filenames в каталогах) технически являются фактическими ресурсами этого пакета. На практике, однако, ресурсами в первую очередь считаются те не-Python артефакты, которые явно предоставлены автором пакета.

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

Ресурсы примерно аналогичны файлам в каталогах, хотя важно помнить, что это всего лишь метафора. Ресурсы и пакеты не обязаны существовать в виде физических файлов и каталогов в файловой системе: например, пакет и его ресурсы могут быть импортированы из zip-файла с помощью zipimport.

Предупреждение

importlib.resources следует той же модели безопасности, что и встроенная функция open(). Передача недоверенных входных данных функциям из этого модуля небезопасна.

Примечание

Автономный бэкпорт этого модуля предоставляет дополнительную информацию об использовании importlib.resources и миграции с pkg_resources на importlib.resources.

Loaders, которые хотят поддерживать чтение ресурсов, должны реализовать метод get_resource_reader(fullname), как указано в importlib.resources.abc.ResourceReader.

class importlib.resources.Anchor

Представляет привязку (anchor) для ресурсов: либо module object, либо имя модуля в виде строки. Определяется как Union[str, ModuleType].

importlib.resources.files(anchor: Anchor | None = None)

Возвращает объект Traversable, представляющий контейнер ресурсов (по аналогии с каталогом) и его ресурсы (по аналогии с файлами). Traversable может содержать другие контейнеры (по аналогии с подкаталогами).

anchor – это необязательный Anchor. Если anchor является пакетом, ресурсы разрешаются относительно этого пакета. Если модулем, ресурсы разрешаются рядом с этим модулем (в том же пакете или корне пакета). Если anchor опущен, используется модуль вызывающего.

Добавлено в версии 3.9.

Изменено в версии 3.12: Параметр package был переименован в anchor. anchor теперь может быть модулем, не являющимся пакетом, и если он опущен, по умолчанию используется модуль вызывающего. package по-прежнему принимается для совместимости, но вызовет DeprecationWarning. Рассмотрите возможность передачи anchor по позиции или использования importlib_resources >= 5.10 для совместимого интерфейса на старых версиях Python.

importlib.resources.as_file(traversable)

Получив объект Traversable, представляющий файл или каталог, обычно из importlib.resources.files(), возвращает менеджер контекста для использования в операторе with. Менеджер контекста предоставляет объект pathlib.Path.

Выход из менеджера контекста удаляет любые временные файлы или каталоги, созданные при извлечении ресурса, например, из zip-файла.

Используйте as_file, когда методов Traversable (read_text и т.д.) недостаточно и требуется реальный файл или каталог в файловой системе.

Добавлено в версии 3.9.

Изменено в версии 3.12: Добавлена поддержка traversable, представляющего каталог.

Функциональное APIFunctional API

Доступен набор упрощенных обратно совместимых вспомогательных функций. Они позволяют выполнять типичные операции одним вызовом функции.

Для всех следующих функций:

  • anchor – это Anchor, как в files(). В отличие от files, его нельзя опустить.

  • path_names – это компоненты пути к ресурсу относительно anchor. Например, чтобы получить текст ресурса с именем info.txt, используйте:

    importlib.resources.read_text(my_module, "info.txt")

    Как и в Traversable.joinpath, отдельные компоненты должны использовать косую черту (/) в качестве разделителя пути. Например, следующие эквивалентны:

    importlib.resources.read_binary(my_module, "pics/painting.png")
importlib.resources.read_binary(my_module, "pics", "painting.png")

    По соображениям обратной совместимости функции, читающие текст, требуют явного указания аргумента encoding, если задано несколько path_names. Например, чтобы получить текст info/chapter1.txt, используйте:

    importlib.resources.read_text(my_module, "info", "chapter1.txt",
                              encoding='utf-8')
importlib.resources.open_binary(anchor, *path_names)

Открывает указанный ресурс для чтения в двоичном режиме.

См. введение для подробностей о anchor и path_names.

Эта функция возвращает объект BinaryIO, то есть двоичный поток, открытый для чтения.

Эта функция примерно эквивалентна следующему:

files(anchor).joinpath(*path_names).open('rb')

Изменено в версии 3.13: Принимаются несколько path_names.

importlib.resources.open_text(anchor, *path_names, encoding='utf-8', errors='strict')

Открывает указанный ресурс для чтения как текст. По умолчанию содержимое читается как строгий UTF-8.

См. введение для подробностей о anchor и path_names. encoding и errors имеют тот же смысл, что и во встроенной функции open().

По причинам обратной совместимости аргумент encoding должен передаваться явно, если указано несколько path_names. Это ограничение планируется снять в Python 3.15.

Эта функция возвращает объект TextIO, то есть текстовый поток, открытый для чтения.

Эта функция примерно эквивалентна следующему:

files(anchor).joinpath(*path_names).open('r', encoding=encoding)

Изменено в версии 3.13: Принимаются несколько path_names. encoding и errors должны передаваться как именованные аргументы.

importlib.resources.read_binary(anchor, *path_names)

Читает и возвращает содержимое указанного ресурса как bytes.

См. введение для подробностей о anchor и path_names.

Эта функция примерно эквивалентна следующему:

files(anchor).joinpath(*path_names).read_bytes()

Изменено в версии 3.13: Принимаются несколько path_names.

importlib.resources.read_text(anchor, *path_names, encoding='utf-8', errors='strict')

Читает и возвращает содержимое указанного ресурса как str. По умолчанию содержимое читается как строгий UTF-8.

См. введение для подробностей о anchor и path_names. encoding и errors имеют тот же смысл, что и во встроенной функции open().

По причинам обратной совместимости аргумент encoding должен передаваться явно, если указано несколько path_names. Это ограничение планируется снять в Python 3.15.

Эта функция примерно эквивалентна следующему:

files(anchor).joinpath(*path_names).read_text(encoding=encoding)

Изменено в версии 3.13: Принимаются несколько path_names. encoding и errors должны передаваться как именованные аргументы.

importlib.resources.path(anchor, *path_names)

Предоставляет путь к ресурсу в виде реального пути файловой системы. Эта функция возвращает контекстный менеджер для использования в операторе with. Контекстный менеджер предоставляет объект pathlib.Path.

Выход из контекстного менеджера удаляет все созданные временные файлы, например, когда ресурс необходимо извлечь из zip-файла.

Например, метод stat() требует реального пути файловой системы; его можно использовать так:

with importlib.resources.path(anchor, "resource.txt") as fspath:
    result = fspath.stat()

См. введение для подробностей о anchor и path_names.

Эта функция примерно эквивалентна следующему:

as_file(files(anchor).joinpath(*path_names))

Изменено в версии 3.13: Принимаются несколько path_names.

importlib.resources.is_resource(anchor, *path_names)

Возвращает True, если указанный ресурс существует, иначе False. Эта функция не считает каталоги ресурсами.

См. введение для подробностей о anchor и path_names.

Эта функция примерно эквивалентна следующему:

files(anchor).joinpath(*path_names).is_file()

Изменено в версии 3.13: Принимаются несколько path_names.

importlib.resources.contents(anchor, *path_names)

Возвращает итератор по именованным элементам внутри пакета или пути. Итератор возвращает имена ресурсов (например, файлов) и не-ресурсов (например, каталогов) в виде str. Итератор не выполняет рекурсивный обход подкаталогов.

См. введение для подробностей о anchor и path_names.

This function is roughly equivalent to:

for resource in files(anchor).joinpath(*path_names).iterdir():
    yield resource.name

Deprecated since version 3.11: Prefer iterdir() as above, which offers more control over the results and richer functionality.