tomllib — разбор файлов TOML

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

Исходный код: Lib/tomllib

Этот модуль предоставляет интерфейс для разбора TOML 1.0.0 (Tom’s Obvious Minimal Language, https://toml.io). Этот модуль не поддерживает запись TOML.

Предупреждение

Будьте осторожны при разборе данных из ненадёжных источников. Вредоносная строка TOML может привести к значительному расходу ресурсов процессора и памяти при декодировании. Рекомендуется ограничивать размер разбираемых данных.

См. также

Пакет Tomli-W — средство записи TOML, которое можно использовать вместе с этим модулем. Оно предоставляет API записи, знакомый пользователям модулей стандартной библиотеки marshal и pickle.

См. также

Пакет TOML Kit — библиотека TOML, сохраняющая форматирование и поддерживающая чтение и запись. Она рекомендуется в качестве замены этого модуля при редактировании уже существующих файлов TOML.

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

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

Прочитать файл TOML. Первый аргумент должен быть доступным для чтения двоичным файловым объектом. Возвращает dict. Преобразует типы TOML в типы Python согласно этой таблице преобразования.

Для каждого значения с плавающей точкой TOML, которое нужно декодировать, будет вызван параметр parse_float, которому будет передана соответствующая строка. По умолчанию это эквивалентно float(num_str). Это можно использовать, чтобы задать другой тип данных или анализатор для значений с плавающей точкой TOML (например, decimal.Decimal). Вызываемый объект не должен возвращать dict или list, иначе будет вызвано исключение ValueError.

Если документ TOML некорректен, будет вызвано исключение TOMLDecodeError.

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

Загрузить TOML из объекта str. Возвращает dict. Преобразует типы TOML в типы Python согласно этой таблице преобразования. Аргумент parse_float имеет то же значение, что и в load().

Если документ TOML некорректен, будет вызвано исключение TOMLDecodeError.

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

exception tomllib.TOMLDecodeError(msg, doc, pos)

Подкласс ValueError со следующими дополнительными атрибутами:

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

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

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

lineno: Номер строки, соответствующей pos.

colno: Номер столбца, соответствующего pos.

Изменено в версии 3.14: Добавлены параметры msg, doc и pos. Добавлены атрибуты msg, doc, pos, lineno и colno.

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

Примеры

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

import tomllib

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

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

import tomllib

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

data = tomllib.loads(toml_str)

Таблица преобразования

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