Модуль tomllib в Python, разбор файлов TOML

Интерфейс для разбора файлов TOML

ВНИМАНИЕ! этот модуль доступен в стандартной библиотеки с версии Python 3.11

Модуль tomllib предоставляет интерфейс для разбора строк и файлов синтаксиса TOML. Этот модуль не поддерживает запись файлов TOML. Он полностью совместим с TOML v1.0.0.

Модуль tomllib - это версия стороннего модуля tomli который (согласно PEP 680) добавлен в стандартную библиотеку в Python 3.11. Разработчики tomli продолжают поддерживать копию в PyPI для версий Python, где модуль стандартной библиотеки tomllib недоступен.

Смотрите также:

сторонний модуль модуль tomli-w, предназначен для записи файлов TOML, который можно использовать вместе со стандартным модулем tomllib. Модуль tomli-w предоставляет API для записи, знакомый пользователям стандартного модуля pickle.
сторонний модуль tomlkit представляет собой парсер TOML, который предоставляет возможность чтения и записи (но гораздо медленнее). Это рекомендуемая замена для модуля tomllib для редактирования уже существующих файлов TOML.

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

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

Функция tomllib.load() читает и разбирает файл TOML. Первый аргумент fp должен быть удобочитаемым и двоичным файловым объектом. Функция возвращает словарь dict. Типы, определенные в разметке TOML преобразуются в типы Python согласно таблицы преобразования.

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

Для недопустимого документа TOML будет вызвана ошибка tomllib.TOMLDecodeError.

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

Функция tomllib.load() читает и разбирает строку s, записанную в формате TOML. Функция возвращает словарь dict. Типы, определенные в разметке TOML преобразуются в типы Python согласно таблицы преобразования.

Аргумент parse_float имеет то же значение, что и в функции tomllib.load().

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

Для недопустимого формата TOML будет вызвана ошибка tomllib.TOMLDecodeError.

`tomllib.TOMLDecodeError`:

Исключение tomllib.TOMLDecodeError представляет собой подкласс ValueError.

Таблица преобразования типов TOML в типы Python

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

Примеры использования модуля `tomllib`:

Разбор строки TOML;
Разбор файла TOML;
Обработка недействительного TOML;
Преобразование float TOML в тип decimal.Decimals Python;
Создание уровня совместимости между tomli и tomllib;

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

import tomllib

toml_str = """
[[players]]
name = "Lehtinen"
number = 26

[[players]]
name = "Numminen"
number = 27
"""

toml_dict = tomllib.loads(toml_str)
assert toml_dict == {
    "players": [{"name": "Lehtinen", "number": 26}, {"name": "Numminen", "number": 27}]
}

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

Файл должен быть открыт в бинарном режиме (с флагом 'rb'). Двоичный режим принудительно декодирует файл как UTF-8 с отключенными универсальными символами новой строки, оба из которых необходимы для правильного синтаксического анализа TOML.

import tomllib

with open("path_to_file/conf.toml", "rb") as f:
    toml_dict = tomllib.load(f)

Обработка недействительного TOML.

Обратите внимание, что сообщения об ошибках считаются только информационными.

import tomllib

try:
    toml_dict = tomllib.loads("]] это недопустимый TOML [[")
except tomllib.TOMLDecodeError:
    print("недопустимый TOML")

Преобразование `float` TOML в тип `decimal.Decimals` Python.

Обратите внимание, что decimal.Decimal можно заменить другим вызываемым объектом, который преобразует число с плавающей запятой TOML из строки в тип Python. Однако decimal.Decimal является практичным выбором для случаев использования, когда нельзя допускать неточностей типа float.

from decimal import Decimal
import tomllib

toml_dict = tomllib.loads("precision-matters = 0.982492", parse_float=Decimal)
assert isinstance(toml_dict["precision-matters"], Decimal)
assert toml_dict["precision-matters"] == Decimal("0.982492")

Если parse_float создаст недопустимые типы, то будет вызван ValueError. Недопустимыми типами являются dict и list, а также их подтипы.

Создание уровня совместимости между `tomli` и `tomllib`.

Версии python 3.11+ поставляются с модулем стандартной библиотеки tomllib - версией tomli. Чтобы создать код, который использует стандартную библиотеку, если она доступна, но при этом без проблем работает с Python 3.6+, сделайте следующее.

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

tomli >= 1.1.0 ; python_version < "3.11"

Затем в своем коде импортируйте синтаксический анализатор TOML, используя следующий резервный механизм:

try:
    import tomllib
except ModuleNotFoundError:
    import tomli as tomllib

# использование
tomllib.loads("['This parses fine with Python 3.6+']")