Документация Python неофициальный перевод
Содержание страницы

importlib.resources – чтение, открытие и доступ к ресурсам пакетовimportlib.resources – Package resource reading, opening and access

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

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

Этот модуль использует систему импорта Python для предоставления доступа к ресурсам внутри пакетов. Если пакет можно импортировать, то можно получить доступ к ресурсам внутри этого пакета. Ресурсы можно открывать или читать в двоичном или текстовом режиме.

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

Примечание

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

Автономный бэкпорт этого модуля предоставляет дополнительную информацию об использовании importlib.resources и миграции с pkg_resources на 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, представляющий контейнер ресурсов для пакета (аналог каталога) и его ресурсы (аналог файлов). Объект Traversable может содержать другие контейнеры (аналог подкаталогов).

package – это либо имя, либо объект модуля, соответствующий требованиям Package.

Новое в версии 3.9.

importlib.resources.as_file(traversable)

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

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

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

Новое в версии 3.9.

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

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

importlib.resources.Resource

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

Тип Resource определён как Union[str, os.PathLike].

importlib.resources.open_binary(package, resource)

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

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

Устарело с версии 3.11: Вызовы этой функции можно заменить на:

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

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

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

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

Устарело с версии 3.11: Вызовы этой функции можно заменить на:

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

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

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

Устарело с версии 3.11: Вызовы этой функции можно заменить на:

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

Читает и возвращает содержимое ресурса внутри пакета в виде str. По умолчанию содержимое читается как строгий UTF-8.

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

Устарело с версии 3.11: Вызовы этой функции можно заменить на:

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

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

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

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

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

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

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

Устарело с версии 3.11: Вызовы этой функции можно заменить на:

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

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

package – это либо имя, либо объект модуля, соответствующий требованиям Package.

Устарело с версии 3.11: Вызовы этой функции можно заменить на:

(resource.name for resource in files(package).iterdir() if resource.is_file())