importlib.resources – чтение, открытие и доступ к ресурсам пакетов

Функциональный API

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

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

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

• path_names — это компоненты имени пути к ресурсу относительно якоря. Например, чтобы получить текст ресурса с именем 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 см. во введении.

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

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

Устарело начиная с версии 3.11: Предпочтительнее использовать iterdir(), описанную выше: она позволяет лучше контролировать результаты и предоставляет более широкие возможности.