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

---

# `tomllib` – Разбор TOML-файлов

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

**Исходный код:** [Lib/tomllib](https://python-all.ru/3.14/library/tomllib.html)

---

Этот модуль предоставляет интерфейс для разбора TOML 1.0.0 (Tom’s Obvious Minimal Language, [https://toml.io](https://python-all.ru/3.14/library/tomllib.html)). Запись TOML не поддерживается.

> **Предупреждение**
>
> Соблюдайте осторожность при разборе данных из ненадёжных источников. Вредоносная строка TOML может заставить декодер потреблять значительные ресурсы ЦП и памяти. Рекомендуется ограничивать размер разбираемых данных.

> **См. также**
>
> Пакет [Tomli-W](https://python-all.ru/3.14/library/tomllib.html) является средством записи TOML, которое можно использовать вместе с этим модулем; оно предоставляет API записи, знакомый пользователям модулей [`marshal`](https://python-all.ru/3.14/library/marshal.html#module-marshal) и [`pickle`](https://python-all.ru/3.14/library/pickle.html#module-pickle) стандартной библиотеки.

> **См. также**
>
> Пакет [TOML Kit](https://python-all.ru/3.14/library/tomllib.html) – это библиотека TOML, сохраняющая стиль, с возможностью как чтения, так и записи. Он является рекомендуемой заменой этого модуля для редактирования уже существующих TOML-файлов.

Этот модуль определяет следующие функции:

#### `tomllib.load(fp, /, *, parse_float=float)`

Читает TOML-файл. Первым аргументом должен быть читаемый двоичный файловый объект. Возвращает [`dict`](https://python-all.ru/3.14/library/stdtypes.html#dict). Преобразует типы TOML в Python согласно этой [таблице соответствия](https://python-all.ru/3.14/library/tomllib.html#toml-to-py-table).

Функция *parse\_float* будет вызвана для строки каждого разбираемого значения TOML с плавающей запятой. По умолчанию она эквивалентна `float(num_str)`. Это позволяет использовать другой тип данных или анализатор для чисел с плавающей запятой TOML (например, [`decimal.Decimal`](https://python-all.ru/3.14/library/decimal.html#decimal.Decimal)). Вызываемый объект не должен возвращать [`dict`](https://python-all.ru/3.14/library/stdtypes.html#dict) или [`list`](https://python-all.ru/3.14/library/stdtypes.html#list), иначе будет возбуждено исключение [`ValueError`](https://python-all.ru/3.14/library/exceptions.html#ValueError).

Исключение [`TOMLDecodeError`](https://python-all.ru/3.14/library/tomllib.html#tomllib.TOMLDecodeError) будет возбуждено при недопустимом документе TOML.

#### `tomllib.loads(s, /, *, parse_float=float)`

Загружает TOML из объекта [`str`](https://python-all.ru/3.14/library/stdtypes.html#str). Возвращает [`dict`](https://python-all.ru/3.14/library/stdtypes.html#dict). Преобразует типы TOML в Python согласно этой [таблице соответствия](https://python-all.ru/3.14/library/tomllib.html#toml-to-py-table). Аргумент *parse\_float* имеет то же значение, что и в [`load()`](https://python-all.ru/3.14/library/tomllib.html#tomllib.load).

Исключение [`TOMLDecodeError`](https://python-all.ru/3.14/library/tomllib.html#tomllib.TOMLDecodeError) будет возбуждено при недопустимом документе TOML.

Доступны следующие исключения:

#### `exception tomllib.TOMLDecodeError(msg, doc, pos)`

Подкласс [`ValueError`](https://python-all.ru/3.14/library/exceptions.html#ValueError) со следующими дополнительными атрибутами:

#### `msg`

Неформатированное сообщение об ошибке.

#### `doc`

Разбираемый документ TOML.

#### `pos`

Индекс в *doc*, на котором произошла ошибка разбора.

#### `lineno`

Строка, соответствующая *pos*.

#### `colno`

Столбец, соответствующий *pos*.

Изменено в версии 3.14: Добавлены параметры *msg*, *doc* и *pos*. Добавлены атрибуты [`msg`](https://python-all.ru/3.14/library/tomllib.html#tomllib.TOMLDecodeError.msg), [`doc`](https://python-all.ru/3.14/library/tomllib.html#tomllib.TOMLDecodeError.doc), [`pos`](https://python-all.ru/3.14/library/tomllib.html#tomllib.TOMLDecodeError.pos), [`lineno`](https://python-all.ru/3.14/library/tomllib.html#tomllib.TOMLDecodeError.lineno) и [`colno`](https://python-all.ru/3.14/library/tomllib.html#tomllib.TOMLDecodeError.colno).

Устарело с версии 3.14: Передача произвольных позиционных аргументов устарела.

## Примеры

Разбор TOML-файла:

```python
import tomllib

with open("pyproject.toml", "rb") as f:
    data = tomllib.load(f)
```

Разбор строки TOML:

```python
import tomllib

toml_str = """
python-version = "3.11.0"
python-implementation = "CPython"
"""

data = tomllib.loads(toml_str)
```

## Таблица соответствия

| TOML | Python |
| --- | --- |
| Документ TOML | dict |
| строка | str |
| целое число | int |
| float | float (настраивается с помощью *parse\_float*) |
| булевый | bool |
| дата-время со смещением | datetime.datetime (атрибут `tzinfo` установлен в экземпляр `datetime.timezone`) |
| локальная дата-время | datetime.datetime (атрибут `tzinfo` установлен в `None`) |
| локальная дата | datetime.date |
| локальное время | datetime.time |
| массив | list |
| таблица | dict |
| встроенная таблица | dict |
| массив таблиц | список словарей |