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

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

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

Этот модуль использует систему импорта 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.Package

Всякий раз, когда функция принимает аргумент Package, вы можете передавать либо module object, либо имя модуля в виде строки. Вы можете передавать только те объекты модуля, у которых __spec__.submodule_search_locations не является None.

Тип Package определяется как Union[str, ModuleType].

importlib.resources.files(package)

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

пакет - это либо имя, либо объект модуля, который соответствует требованиям Package.

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

importlib.resources.as_file(traversable)

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

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

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

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

Устаревшие функции

Более старый, устаревший набор функций все еще доступен, но его планируется удалить в будущей версии Python. Основным недостатком этих функций является то, что они не поддерживают каталоги: предполагается, что все ресурсы расположены непосредственно в пакете.

importlib.resources.Resource

Для аргументов resource приведенных ниже функций вы можете передать имя ресурса в виде строки или path-like object.

Тип Resource определяется как Union[str, os.PathLike].

importlib.resources.open_binary(package, resource)

Откройте для двоичного чтения ресурс внутри пакета.

пакет - это либо имя, либо объект модуля, который соответствует требованиям Package. resource - это имя ресурса, который нужно открыть в package; оно может не содержать разделителей путей и не содержать вложенных ресурсов (т.е. это не может быть каталог). Эта функция возвращает экземпляр typing.BinaryIO, двоичный поток ввода-вывода, открытый для чтения.

Не рекомендуется, начиная с версии 3.11: Вызовы этой функции могут быть заменены на:

files(package).joinpath(resource).open('rb')
importlib.resources.open_text(package, resource, encoding='utf-8', errors='strict')

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

пакет - это либо имя, либо объект модуля, который соответствует требованиям Package. resource - это имя ресурса, который нужно открыть в package; оно может не содержать разделителей путей и не содержать вложенных ресурсов (т.е. это не может быть каталог). кодировка и ошибки имеют то же значение, что и при использовании встроенного open().

Эта функция возвращает экземпляр typing.TextIO, текстовый поток ввода-вывода, открытый для чтения.

Не рекомендуется, начиная с версии 3.11: Вызовы этой функции могут быть заменены на:

files(package).joinpath(resource).open('r', encoding=encoding)
importlib.resources.read_binary(package, resource)

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

пакет - это либо имя, либо объект модуля, который соответствует требованиям Package. resource - это имя ресурса, который нужно открыть в package; оно может не содержать разделителей путей и не содержать вложенных ресурсов (т.е. это не может быть каталог). Эта функция возвращает содержимое ресурса в виде bytes.

Не рекомендуется, начиная с версии 3.11: Вызовы этой функции могут быть заменены на:

files(package).joinpath(resource).read_bytes()
importlib.resources.read_text(package, resource, encoding='utf-8', errors='strict')

Считывает и возвращает содержимое resource в package в виде str. По умолчанию содержимое считывается в строгом формате UTF-8.

пакет - это либо имя, либо объект модуля, который соответствует требованиям Package. resource - это имя ресурса, который нужно открыть в package; оно может не содержать разделителей путей и не содержать вложенных ресурсов (т.е. это не может быть каталог). кодировка и ошибки имеют то же значение, что и при использовании встроенного open(). Эта функция возвращает содержимое ресурса в виде str.

Не рекомендуется, начиная с версии 3.11: Вызовы этой функции могут быть заменены на:

files(package).joinpath(resource).read_text(encoding=encoding)
importlib.resources.path(package, resource)

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

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

пакет - это либо имя, либо объект модуля, который соответствует требованиям Package. resource - это имя ресурса, который нужно открыть в package; оно может не содержать разделителей путей и не содержать вложенных ресурсов (т.е. это не может быть каталог).

Не рекомендуется, начиная с версии 3.11: Вызовы этой функции можно заменить с помощью as_file():

as_file(files(package).joinpath(resource))
importlib.resources.is_resource(package, name)

Возвращает True, если в пакете есть ресурс с именем name, в противном случае False. Эта функция не рассматривает каталоги как ресурсы. пакет - это либо имя, либо объект модуля, который соответствует требованиям Package.

Не рекомендуется, начиная с версии 3.11: Вызовы этой функции могут быть заменены на:

files(package).joinpath(resource).is_file()
importlib.resources.contents(package)

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

пакет - это либо имя, либо объект модуля, который соответствует требованиям Package.

Не рекомендуется, начиная с версии 3.11: Вызовы этой функции могут быть заменены на:

(resource.name for resource in files(package).iterdir() if resource.is_file())
importlib — Реализация import
importlib.resources.abc – Абстрактные базовые классы для ресурсов
Вернуться на верх