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. Аргументы encoding и errors необходимо задавать как именованные.

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(), которая предоставляет больше контроля над результатами и более широкие возможности.