`importlib.resources.md`

203 строк · 16.6 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.16/library/importlib.resources.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `importlib.resources` – чтение, открытие и доступ к ресурсам пакетов89**Исходный код:** [Lib/importlib/resources/\_\_init\_\_.py](https://python-all.ru/src/main/Lib/importlib/resources/__init__.py)1011---1213Добавлено в версии 3.7.1415Этот модуль использует систему импорта Python для обеспечения доступа к *ресурсам* внутри *пакетов*.1617«Ресурсы» – это файлоподобные ресурсы, связанные с модулем или пакетом в Python. Ресурсы могут находиться непосредственно в пакете, в подкаталоге этого пакета или рядом с модулями вне пакета. Ресурсы могут быть текстовыми или двоичными. Как следствие, исходные файлы модулей Python (.py), артефакты компиляции (pycache) и артефакты установки (например, [`reserved filenames`](https://python-all.ru/3.16/library/os.path.html#os.path.isreserved) в каталогах) технически являются фактическими ресурсами этого пакета. На практике, однако, ресурсами в первую очередь считаются те не-Python артефакты, которые явно предоставлены автором пакета.1819Ресурсы можно открывать или читать как в двоичном, так и в текстовом режиме.2021Ресурсы примерно аналогичны файлам в каталогах, хотя важно помнить, что это всего лишь метафора. Ресурсы и пакеты **не** обязаны существовать в виде физических файлов и каталогов в файловой системе: например, пакет и его ресурсы могут быть импортированы из zip-файла с помощью [`zipimport`](https://python-all.ru/3.16/library/zipimport.html#module-zipimport).2223> **Предупреждение**24>25> `importlib.resources` следует той же модели безопасности, что и встроенная функция [`open()`](https://python-all.ru/3.16/library/functions.html#open). Передача недоверенных входных данных функциям из этого модуля небезопасна.2627> **Примечание**28>29> Автономный бэкпорт этого модуля предоставляет дополнительную информацию об [использовании importlib.resources](https://python-all.ru/3.16/library/importlib.resources.html) и [миграции с pkg\_resources на importlib.resources](https://python-all.ru/3.16/library/importlib.resources.html).3031[`Loaders`](https://python-all.ru/3.16/library/importlib.html#importlib.abc.Loader), которые хотят поддерживать чтение ресурсов, должны реализовать метод `get_resource_reader(fullname)`, как указано в [`importlib.resources.abc.ResourceReader`](https://python-all.ru/3.16/library/importlib.resources.abc.html#importlib.resources.abc.ResourceReader).3233#### `class importlib.resources.Anchor`3435Представляет привязку (anchor) для ресурсов: либо [`module object`](https://python-all.ru/3.16/library/types.html#types.ModuleType), либо имя модуля в виде строки. Определяется как `Union[str, ModuleType]`.3637#### `importlib.resources.files(anchor: Anchor | None = None)`3839Возвращает объект [`Traversable`](https://python-all.ru/3.16/library/importlib.resources.abc.html#importlib.resources.abc.Traversable), представляющий контейнер ресурсов (по аналогии с каталогом) и его ресурсы (по аналогии с файлами). Traversable может содержать другие контейнеры (по аналогии с подкаталогами).4041*anchor* – это необязательный [`Anchor`](https://python-all.ru/3.16/library/importlib.resources.html#importlib.resources.Anchor). Если anchor является пакетом, ресурсы разрешаются относительно этого пакета. Если модулем, ресурсы разрешаются рядом с этим модулем (в том же пакете или корне пакета). Если anchor опущен, используется модуль вызывающего.4243Добавлено в версии 3.9.4445Изменено в версии 3.12: *package* был переименован в *anchor*. *package* по-прежнему принимался, но был объявлен устаревшим.4647Изменено в версии 3.15: параметр *package* был полностью удален. *anchor* теперь может быть модулем, не являющимся пакетом, и если он опущен, по умолчанию будет использоваться модуль вызывающего кода. *package* больше не принимается начиная с Python 3.15. Рассмотрите возможность передачи anchor позиционно или использования `importlib_resources >= 5.10` для совместимого интерфейса в старых версиях Python.4849#### `importlib.resources.as_file(traversable)`5051Получив объект [`Traversable`](https://python-all.ru/3.16/library/importlib.resources.abc.html#importlib.resources.abc.Traversable), представляющий файл или каталог, обычно из [`importlib.resources.files()`](https://python-all.ru/3.16/library/importlib.resources.html#importlib.resources.files), возвращает менеджер контекста для использования в операторе [`with`](https://python-all.ru/3.16/reference/compound_stmts.html#with). Менеджер контекста предоставляет объект [`pathlib.Path`](https://python-all.ru/3.16/library/pathlib.html#pathlib.Path).5253Выход из менеджера контекста удаляет любые временные файлы или каталоги, созданные при извлечении ресурса, например, из zip-файла.5455Используйте `as_file`, когда методов Traversable (`read_text` и т.д.) недостаточно и требуется реальный файл или каталог в файловой системе.5657Добавлено в версии 3.9.5859Изменено в версии 3.12: Добавлена поддержка *traversable*, представляющего каталог.6061## Функциональное API6263Доступен набор упрощенных обратно совместимых вспомогательных функций. Они позволяют выполнять типичные операции одним вызовом функции.6465Для всех следующих функций:6667- *anchor* – это [`Anchor`](https://python-all.ru/3.16/library/importlib.resources.html#importlib.resources.Anchor), как в [`files()`](https://python-all.ru/3.16/library/importlib.resources.html#importlib.resources.files). В отличие от `files`, его нельзя опустить.68- *path\_names* – это компоненты пути к ресурсу относительно anchor. Например, чтобы получить текст ресурса с именем `info.txt`, используйте:6970  ```python71  importlib.resources.read_text(my_module, "info.txt")72  ```7374  Как и в [`Traversable.joinpath`](https://python-all.ru/3.16/library/importlib.resources.abc.html#importlib.resources.abc.Traversable), отдельные компоненты должны использовать косую черту (`/`) в качестве разделителя пути. Например, следующие эквивалентны:7576  ```python77  importlib.resources.read_binary(my_module, "pics/painting.png")78  importlib.resources.read_binary(my_module, "pics", "painting.png")79  ```8081  По соображениям обратной совместимости функции, читающие текст, требуют явного указания аргумента *encoding*, если задано несколько *path\_names*. Например, чтобы получить текст `info/chapter1.txt`, используйте:8283  ```python84  importlib.resources.read_text(my_module, "info", "chapter1.txt",85                                encoding='utf-8')86  ```8788#### `importlib.resources.open_binary(anchor, *path_names)`8990Открывает указанный ресурс для чтения в двоичном режиме.9192См. [введение](https://python-all.ru/3.16/library/importlib.resources.html#importlib-resources-functional) для подробностей о *anchor* и *path\_names*.9394Эта функция возвращает объект [`BinaryIO`](https://python-all.ru/3.16/library/typing.html#typing.BinaryIO), то есть двоичный поток, открытый для чтения.9596This function is roughly equivalent to:9798```python99files(anchor).joinpath(*path_names).open('rb')100```101102Изменено в версии 3.13: Принимаются несколько *path\_names*.103104#### `importlib.resources.open_text(anchor, *path_names, encoding='utf-8', errors='strict')`105106Открывает указанный ресурс для чтения как текст. По умолчанию содержимое читается как строгий UTF-8.107108См. [введение](https://python-all.ru/3.16/library/importlib.resources.html#importlib-resources-functional) для подробностей о *anchor* и *path\_names*. *encoding* и *errors* имеют тот же смысл, что и во встроенной функции [`open()`](https://python-all.ru/3.16/library/functions.html#open).109110По причинам обратной совместимости аргумент *encoding* должен передаваться явно, если указано несколько *path\_names*. Это ограничение планируется снять в Python 3.15.111112Эта функция возвращает объект [`TextIO`](https://python-all.ru/3.16/library/typing.html#typing.TextIO), то есть текстовый поток, открытый для чтения.113114This function is roughly equivalent to:115116```python117files(anchor).joinpath(*path_names).open('r', encoding=encoding)118```119120Изменено в версии 3.13: Принимаются несколько *path\_names*. *encoding* и *errors* должны передаваться как именованные аргументы.121122#### `importlib.resources.read_binary(anchor, *path_names)`123124Читает и возвращает содержимое указанного ресурса как [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes).125126См. [введение](https://python-all.ru/3.16/library/importlib.resources.html#importlib-resources-functional) для подробностей о *anchor* и *path\_names*.127128This function is roughly equivalent to:129130```python131files(anchor).joinpath(*path_names).read_bytes()132```133134Изменено в версии 3.13: Принимаются несколько *path\_names*.135136#### `importlib.resources.read_text(anchor, *path_names, encoding='utf-8', errors='strict')`137138Читает и возвращает содержимое указанного ресурса как [`str`](https://python-all.ru/3.16/library/stdtypes.html#str). По умолчанию содержимое читается как строгий UTF-8.139140См. [введение](https://python-all.ru/3.16/library/importlib.resources.html#importlib-resources-functional) для подробностей о *anchor* и *path\_names*. *encoding* и *errors* имеют тот же смысл, что и во встроенной функции [`open()`](https://python-all.ru/3.16/library/functions.html#open).141142По причинам обратной совместимости аргумент *encoding* должен передаваться явно, если указано несколько *path\_names*. Это ограничение планируется снять в Python 3.15.143144This function is roughly equivalent to:145146```python147files(anchor).joinpath(*path_names).read_text(encoding=encoding)148```149150Изменено в версии 3.13: Принимаются несколько *path\_names*. *encoding* и *errors* должны передаваться как именованные аргументы.151152#### `importlib.resources.path(anchor, *path_names)`153154Предоставляет путь к *ресурсу* в виде реального пути файловой системы. Эта функция возвращает контекстный менеджер для использования в операторе [`with`](https://python-all.ru/3.16/reference/compound_stmts.html#with). Контекстный менеджер предоставляет объект [`pathlib.Path`](https://python-all.ru/3.16/library/pathlib.html#pathlib.Path).155156Выход из контекстного менеджера удаляет все созданные временные файлы, например, когда ресурс необходимо извлечь из zip-файла.157158Например, метод [`stat()`](https://python-all.ru/3.16/library/pathlib.html#pathlib.Path.stat) требует реального пути файловой системы; его можно использовать так:159160```python161with importlib.resources.path(anchor, "resource.txt") as fspath:162    result = fspath.stat()163```164165См. [введение](https://python-all.ru/3.16/library/importlib.resources.html#importlib-resources-functional) для подробностей о *anchor* и *path\_names*.166167This function is roughly equivalent to:168169```python170as_file(files(anchor).joinpath(*path_names))171```172173Изменено в версии 3.13: Принимаются несколько *path\_names*.174175#### `importlib.resources.is_resource(anchor, *path_names)`176177Возвращает `True`, если указанный ресурс существует, иначе `False`. Эта функция не считает каталоги ресурсами.178179См. [введение](https://python-all.ru/3.16/library/importlib.resources.html#importlib-resources-functional) для подробностей о *anchor* и *path\_names*.180181This function is roughly equivalent to:182183```python184files(anchor).joinpath(*path_names).is_file()185```186187Изменено в версии 3.13: Принимаются несколько *path\_names*.188189#### `importlib.resources.contents(anchor, *path_names)`190191Возвращает итератор по именованным элементам внутри пакета или пути. Итератор возвращает имена ресурсов (например, файлов) и не-ресурсов (например, каталогов) в виде [`str`](https://python-all.ru/3.16/library/stdtypes.html#str). Итератор не выполняет рекурсивный обход подкаталогов.192193См. [введение](https://python-all.ru/3.16/library/importlib.resources.html#importlib-resources-functional) для подробностей о *anchor* и *path\_names*.194195This function is roughly equivalent to:196197```python198for resource in files(anchor).joinpath(*path_names).iterdir():199    yield resource.name200```201202Deprecated since version 3.11: Prefer `iterdir()` as above, which offers more control over the results and richer functionality.203