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