Сообщить об ошибке.

Модуль 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
tabledict
stringstr
integerint
floatfloat (настраивается с помощью аргумента parse_float)
booleanbool
offset date-timedatetime.datetime (атрибут tzinfo, установленный для экземпляра datetime.timezone)
local date-timedatetime.datetime (для атрибута tzinfo установлено значение None)
local datedatetime.date
local timedatetime.time
arraylist

Примеры использования модуля 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+']")