> **Источник:** https://python-all.ru/3.16/library/importlib.resources.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

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

**Исходный код:** [Lib/importlib/resources/\_\_init\_\_.py](https://python-all.ru/src/main/Lib/importlib/resources/__init__.py)

---

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

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

«Ресурсы» – это файлоподобные ресурсы, связанные с модулем или пакетом в Python. Ресурсы могут находиться непосредственно в пакете, в подкаталоге этого пакета или рядом с модулями вне пакета. Ресурсы могут быть текстовыми или двоичными. Как следствие, исходные файлы модулей Python (.py), артефакты компиляции (pycache) и артефакты установки (например, [`reserved filenames`](https://python-all.ru/3.16/library/os.path.html#os.path.isreserved) в каталогах) технически являются фактическими ресурсами этого пакета. На практике, однако, ресурсами в первую очередь считаются те не-Python артефакты, которые явно предоставлены автором пакета.

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

Ресурсы примерно аналогичны файлам в каталогах, хотя важно помнить, что это всего лишь метафора. Ресурсы и пакеты **не** обязаны существовать в виде физических файлов и каталогов в файловой системе: например, пакет и его ресурсы могут быть импортированы из zip-файла с помощью [`zipimport`](https://python-all.ru/3.16/library/zipimport.html#module-zipimport).

> **Предупреждение**
>
> `importlib.resources` следует той же модели безопасности, что и встроенная функция [`open()`](https://python-all.ru/3.16/library/functions.html#open). Передача недоверенных входных данных функциям из этого модуля небезопасна.

> **Примечание**
>
> Автономный бэкпорт этого модуля предоставляет дополнительную информацию об [использовании 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).

[`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).

#### `class importlib.resources.Anchor`

Представляет привязку (anchor) для ресурсов: либо [`module object`](https://python-all.ru/3.16/library/types.html#types.ModuleType), либо имя модуля в виде строки. Определяется как `Union[str, ModuleType]`.

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

Возвращает объект [`Traversable`](https://python-all.ru/3.16/library/importlib.resources.abc.html#importlib.resources.abc.Traversable), представляющий контейнер ресурсов (по аналогии с каталогом) и его ресурсы (по аналогии с файлами). Traversable может содержать другие контейнеры (по аналогии с подкаталогами).

*anchor* – это необязательный [`Anchor`](https://python-all.ru/3.16/library/importlib.resources.html#importlib.resources.Anchor). Если anchor является пакетом, ресурсы разрешаются относительно этого пакета. Если модулем, ресурсы разрешаются рядом с этим модулем (в том же пакете или корне пакета). Если anchor опущен, используется модуль вызывающего.

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

Изменено в версии 3.12: *package* был переименован в *anchor*. *package* по-прежнему принимался, но был объявлен устаревшим.

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

#### `importlib.resources.as_file(traversable)`

Получив объект [`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).

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

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

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

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

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

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

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

- *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`, его нельзя опустить.
- *path\_names* – это компоненты пути к ресурсу относительно anchor. Например, чтобы получить текст ресурса с именем `info.txt`, используйте:

  ```python
  importlib.resources.read_text(my_module, "info.txt")
  ```

  Как и в [`Traversable.joinpath`](https://python-all.ru/3.16/library/importlib.resources.abc.html#importlib.resources.abc.Traversable), отдельные компоненты должны использовать косую черту (`/`) в качестве разделителя пути. Например, следующие эквивалентны:

  ```python
  importlib.resources.read_binary(my_module, "pics/painting.png")
  importlib.resources.read_binary(my_module, "pics", "painting.png")
  ```

  По соображениям обратной совместимости функции, читающие текст, требуют явного указания аргумента *encoding*, если задано несколько *path\_names*. Например, чтобы получить текст `info/chapter1.txt`, используйте:

  ```python
  importlib.resources.read_text(my_module, "info", "chapter1.txt",
                                encoding='utf-8')
  ```

#### `importlib.resources.open_binary(anchor, *path_names)`

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

См. [введение](https://python-all.ru/3.16/library/importlib.resources.html#importlib-resources-functional) для подробностей о *anchor* и *path\_names*.

Эта функция возвращает объект [`BinaryIO`](https://python-all.ru/3.16/library/typing.html#typing.BinaryIO), то есть двоичный поток, открытый для чтения.

This function is roughly equivalent to:

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

Изменено в версии 3.13: Принимаются несколько *path\_names*.

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

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

См. [введение](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).

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

Эта функция возвращает объект [`TextIO`](https://python-all.ru/3.16/library/typing.html#typing.TextIO), то есть текстовый поток, открытый для чтения.

This function is roughly equivalent to:

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

Изменено в версии 3.13: Принимаются несколько *path\_names*. *encoding* и *errors* должны передаваться как именованные аргументы.

#### `importlib.resources.read_binary(anchor, *path_names)`

Читает и возвращает содержимое указанного ресурса как [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes).

См. [введение](https://python-all.ru/3.16/library/importlib.resources.html#importlib-resources-functional) для подробностей о *anchor* и *path\_names*.

This function is roughly equivalent to:

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

Изменено в версии 3.13: Принимаются несколько *path\_names*.

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

Читает и возвращает содержимое указанного ресурса как [`str`](https://python-all.ru/3.16/library/stdtypes.html#str). По умолчанию содержимое читается как строгий UTF-8.

См. [введение](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).

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

This function is roughly equivalent to:

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

Изменено в версии 3.13: Принимаются несколько *path\_names*. *encoding* и *errors* должны передаваться как именованные аргументы.

#### `importlib.resources.path(anchor, *path_names)`

Предоставляет путь к *ресурсу* в виде реального пути файловой системы. Эта функция возвращает контекстный менеджер для использования в операторе [`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).

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

Например, метод [`stat()`](https://python-all.ru/3.16/library/pathlib.html#pathlib.Path.stat) требует реального пути файловой системы; его можно использовать так:

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

См. [введение](https://python-all.ru/3.16/library/importlib.resources.html#importlib-resources-functional) для подробностей о *anchor* и *path\_names*.

This function is roughly equivalent to:

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

Изменено в версии 3.13: Принимаются несколько *path\_names*.

#### `importlib.resources.is_resource(anchor, *path_names)`

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

См. [введение](https://python-all.ru/3.16/library/importlib.resources.html#importlib-resources-functional) для подробностей о *anchor* и *path\_names*.

This function is roughly equivalent to:

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

Изменено в версии 3.13: Принимаются несколько *path\_names*.

#### `importlib.resources.contents(anchor, *path_names)`

Возвращает итератор по именованным элементам внутри пакета или пути. Итератор возвращает имена ресурсов (например, файлов) и не-ресурсов (например, каталогов) в виде [`str`](https://python-all.ru/3.16/library/stdtypes.html#str). Итератор не выполняет рекурсивный обход подкаталогов.

См. [введение](https://python-all.ru/3.16/library/importlib.resources.html#importlib-resources-functional) для подробностей о *anchor* и *path\_names*.

This function is roughly equivalent to:

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

Deprecated since version 3.11: Prefer `iterdir()` as above, which offers more control over the results and richer functionality.