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

Исходный код: 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: Представляет якорь для ресурсов: либо module object, либо имя модуля в виде строки. Определён как Union[str, ModuleType].

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

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

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

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

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

importlib.resources.as_file(traversable)

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

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

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

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

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

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

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

importlib.resources.Package

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

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

Устарело с версии 3.12.

importlib.resources.Resource

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

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

importlib.resources.open_binary(package, resource)

Открывает resource в package для чтения в двоичном режиме.

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

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

files(package).joinpath(resource).open('rb')

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

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

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

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

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

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

importlib.resources.read_binary(package, resource)

Читает содержимое resource в package и возвращает его как 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')

Читает содержимое resource в package и возвращает его как 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)

Возвращает путь к 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 — это либо имя, либо объект модуля, соответствующий требованиям 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())

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