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

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

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

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

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

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

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

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

Примечание

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

Автономный бэкпорт этого модуля предоставляет дополнительную информацию об использовании importlib.resources и миграции с pkg_resources на importlib.resources.

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

class importlib.resources.Anchor

Представляет привязку (anchor) для ресурсов: либо module object, либо имя модуля в виде строки. Определяется как Union[str, ModuleType].

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

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

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

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

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

importlib.resources.as_file(traversable)

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

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

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

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

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

Функциональное APIFunctional API

Набор функций, ранее объявленных устаревшими, по-прежнему доступен. Их главный недостаток – отсутствие поддержки каталогов: они предполагают, что все ресурсы находятся непосредственно внутри пакета.

importlib.resources.Package

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

Тип Package определён как Union[str, ModuleType].

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, открытый для чтения.

This function is roughly equivalent to:

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, открытый для чтения.

This function is roughly equivalent to:

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

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

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

This function is roughly equivalent to:

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.

This function is roughly equivalent to:

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

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

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

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

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

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

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

This function is roughly equivalent to:

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

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

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

This function is roughly equivalent to:

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