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

Исходный код: 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.

END_OF_DOCUMENT_MARKER

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

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

importlib.resources.Resource

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

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

importlib.resources.open_binary(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. Ресурс — это имя ресурса для открытия внутри пакета; он не может содержать разделители путей и не может иметь подресурсы (т.е. он не может быть каталогом). encoding и errors имеют то же значение, что и у встроенной функции open().

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

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

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

importlib.resources.read_binary(package, resource)

Прочитать и вернуть содержимое ресурса внутри пакета как bytes.

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

files(package).joinpath(resource).read_bytes()

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

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

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

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

files(package).joinpath(resource).read_text(encoding=encoding)

importlib.resources.path(package, resource)

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

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

Устарело начиная с версии 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())

© 2001–2023 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.11/library/importlib.resources.html