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. Если 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, представляющего каталог.

END_OF_DOCUMENT_MARKER ```

Функциональный API

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

Для всех следующих функций:

якорь — это Anchor, как в files(). В отличие от files, его нельзя опустить.
имена_путей — это компоненты имени пути ресурса, относительные к якорю. Например, чтобы получить текст ресурса под названием info.txt, используйте:
```
importlib.resources.read_text(my_module, "info.txt")
```
Как и Traversable.joinpath, отдельные компоненты должны использовать прямой слэш (/) в качестве разделителя путей. Например, следующие варианты эквивалентны:
```
importlib.resources.read_binary(my_module, "pics/painting.png")
importlib.resources.read_binary(my_module, "pics", "painting.png")
```
По соображениям обратной совместимости, функции, которые считывают текст, требуют явного аргумента кодировка, если указано несколько имен_путей. Например, чтобы получить текст info/chapter1.txt, используйте:
```
importlib.resources.read_text(my_module, "info", "chapter1.txt",
                              encoding='utf-8')
```

importlib.resources.open_binary(anchor, *path_names)

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

См. введение для получения подробной информации об якоре и имен_путей.

Эта функция возвращает объект BinaryIO, то есть двоичный поток, открытый для чтения.

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

files(anchor).joinpath(*path_names).open('rb')

Изменено в версии 3.13: Принимаются несколько имен_путей.

importlib.resources.open_text(anchor, *path_names, encoding='utf-8', errors='strict')

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

См. введение для получения подробной информации об якоре и имен_путей. кодировка и ошибки имеют то же значение, что и в встроенной функции open().

По соображениям обратной совместимости аргумент кодировка должен быть явно указан, если указано несколько имен_путей. Это ограничение планируется удалить в Python 3.15.

Эта функция возвращает объект TextIO, то есть текстовый поток, открытый для чтения.

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

files(anchor).joinpath(*path_names).open('r', encoding=encoding)

Изменено в версии 3.13: Принимаются несколько имен_путей. кодировка и ошибки должны быть указаны в качестве ключевых аргументов.

importlib.resources.read_binary(anchor, *path_names)

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

См. введение для получения подробной информации об якоре и имен_путей.

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

files(anchor).joinpath(*path_names).read_bytes()

Изменено в версии 3.13: Принимаются несколько имен_путей.

importlib.resources.read_text(anchor, *path_names, encoding='utf-8', errors='strict')

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

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

files(anchor).joinpath(*path_names).read_text(encoding=encoding)

importlib.resources.path(anchor, *path_names)

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

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

Например, метод stat() требует фактического пути файловой системы; его можно использовать следующим образом:

with importlib.resources.path(anchor, "resource.txt") as fspath:
    result = fspath.stat()

См. введение для получения подробной информации об якоре и имен_путей.

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

as_file(files(anchor).joinpath(*path_names))

importlib.resources.is_resource(anchor, *path_names)

Возвращает True , если указанный ресурс существует, иначе False. Эта функция не рассматривает каталоги как ресурсы.

См. введение для получения подробной информации об якоре и имен_путей.

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

files(anchor).joinpath(*path_names).is_file()

Изменено в версии 3.13: Принимаются несколько имен_путей.

importlib.resources.contents(anchor, *path_names)

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

См. введение для получения подробной информации об якоре и имен_путей.

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

for resource in files(anchor).joinpath(*path_names).iterdir():
    yield resource.name

Устарело начиная с версии 3.11: Предпочтительнее iterdir() , как указано выше, что обеспечивает больший контроль над результатами и более богатые возможности.

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