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

Источник: Lib/importlib/resources/__init__.py

---

Added in version 3.7.

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

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

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

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

Примечание

Этот модуль предоставляет функциональность, аналогичную pkg_resources Basic Resource Access без излишней производительности этого пакета. Это упрощает чтение ресурсов, включенных в пакеты, с более стабильной и последовательной семантикой.

В отдельном бэкпорте этого модуля содержится дополнительная информация о using importlib.resources и migrating from pkg_resources to importlib.resources.

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

class importlib.resources.Anchor

Представляет собой якорь для ресурсов, либо module object, либо имя модуля в виде строки. Определяется как Union[str, ModuleType].

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

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

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

Added in version 3.9.

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

importlib.resources.as_file(traversable)

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

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

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

Added in version 3.9.

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

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

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

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

• якорь - это 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")
  

  По соображениям обратной совместимости функции, читающие текст, требуют явного аргумента кодировка, если задано несколько имен_путей. Например, чтобы получить текст 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 см. в the introduction.

Эта функция возвращает объект 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.

Подробности о якорях и именах_путей см. в the introduction. кодировка и ошибки имеют то же значение, что и во встроенной версии open().

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

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

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

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

Изменено в версии 3.13: Допускается использование нескольких имен path_names. кодировка и ошибки должны быть указаны в качестве аргументов ключевых слов.

importlib.resources.read_binary(anchor, *path_names)

Считывает и возвращает содержимое именованного ресурса в виде bytes.

Подробности о anchor и path_names см. в the introduction.

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

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.

Подробности о якорях и именах_путей см. в the introduction. кодировка и ошибки имеют то же значение, что и во встроенной версии open().

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

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

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

Изменено в версии 3.13: Допускается использование нескольких имен path_names. кодировка и ошибки должны быть указаны в качестве аргументов ключевых слов.

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 см. в the introduction.

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

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

Изменено в версии 3.13: Допускается использование нескольких имен path_names. кодировка и ошибки должны быть указаны в качестве аргументов ключевых слов.

importlib.resources.is_resource(anchor, *path_names)

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

Подробности о anchor и path_names см. в the introduction.

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

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

Изменено в версии 3.13: Допускается использование нескольких имен path_names.

importlib.resources.contents(anchor, *path_names)

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

Подробности о anchor и path_names см. в the introduction.

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

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

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