TOML за 8 минут

TOML (Tom's Obvious, Minimal Language) — формат конфигурационных файлов, который читается как обычный текст и однозначно превращается в хеш-таблицу. Весь язык умещается на одной странице — изучаем его прямо в комментариях кода.

Что такое TOML и где применяется

# TOML — формат для конфигов, придуманный Томом Престоном-Вернером.
# Цель: быть очевидным для человека и легко парситься в словарь/хеш.
# Расширение файла — .toml

# Где встречается:
#   Cargo.toml      — манифест пакетов в Rust
#   pyproject.toml  — конфиг сборки и инструментов в Python
#   config.toml     — Hugo, многие CLI-утилиты и сервисы

# Комментарий начинается с решётки и идёт до конца строки.
key = "value"  # комментарий можно писать и после значения

# Файл TOML целиком — это одна большая таблица (словарь).
# Регистр важен: Name и name — разные ключи.

Ключи и значения

Базовая единица TOML — пара key = value. Пробелы вокруг знака равно игнорируются, но пара обязана уместиться в одной строке.

# Простой ключ: буквы, цифры, _ и - без кавычек
name = "codechick"
port = 8080

# Ключ в кавычках — если нужны пробелы, точки или спецсимволы
"ключ с пробелами" = true
"127.0.0.1" = "localhost"

# Точечные ключи создают вложенные таблицы на лету:
server.host = "example.com"   # это таблица server с ключом host
server.port = 443             # та же таблица server
# Эквивалентно:  server = { host = "example.com", port = 443 }

# Дублировать один и тот же ключ нельзя — это ошибка.

Строки

# Базовая строка (basic) — в двойных кавычках, понимает экранирование
greeting = "Привет,\nмир!"        # \n — перевод строки, \t — таб
path = "C:\\Users\\dev"           # обратный слеш экранируется как \\
unicode = "\u0041"                # \u и \U — символы по коду (A)

# Литеральная строка (literal) — в одинарных кавычках, БЕЗ экранирования
winpath = 'C:\Users\dev'          # слеши остаются как есть
regex = '\d{3}-\d{2}'             # удобно для регулярок и путей

# Многострочная базовая — три двойные кавычки
bio = """
Первая строка
Вторая строка"""
# Обратный слеш в конце строки "съедает" перенос и пробелы:
long = """один \
          два"""            # получится: один два

# Многострочная литеральная — три одинарные кавычки, всё дословно
verse = '''
текст 'с кавычками' внутри
и \без экранирования'''

Числа, булевы значения и даты

TOML различает целые и дробные числа, логические значения и полноценные даты по стандарту RFC 3339.

# Целые числа (integer) — можно с разделителями-подчёркиваниями
count = 42
big = 1_000_000          # _ для читаемости, на значение не влияет
negative = -17
hex = 0xDEADBEEF         # 16-ричное
octal = 0o755            # 8-ричное
binary = 0b1010          # 2-ичное

# Числа с плавающей точкой (float)
ratio = 3.14
exp = 5e3                # 5000.0
inf = inf                # бесконечность; есть -inf и nan

# Булевы значения (boolean) — только в нижнем регистре
enabled = true
debug = false

# Дата и время (datetime) — без кавычек, по RFC 3339
moment = 2026-06-16T09:30:00Z          # дата-время со смещением UTC
local = 2026-06-16T12:00:00+03:00      # со своим часовым поясом
day = 2026-06-16                       # только дата
clock = 09:30:00                       # только время

Таблицы

Таблица — это именованная группа ключей, объявляется заголовком в квадратных скобках. Всё, что идёт после заголовка, попадает внутрь этой таблицы.

# Заголовок таблицы — имя в квадратных скобках
[database]
host = "localhost"      # это database.host
port = 5432             # это database.port

[server]
ip = "0.0.0.0"          # новая таблица — отсчёт пошёл заново

# Вложенные таблицы — точка в имени заголовка
[server.tls]
enabled = true          # это server.tls.enabled
cert = "/etc/cert.pem"

# Промежуточные таблицы создаются автоматически:
[a.b.c]
value = 1               # a и a.b возникнут сами собой

Массивы

# Массив — значения в квадратных скобках через запятую
ports = [8000, 8001, 8002]
names = ["alice", "bob", "carol"]
flags = [true, false, true]

# Массив можно разбить на несколько строк, пробелы не важны
colors = [
  "red",
  "green",
  "blue",          # завершающая запятая разрешена
]

# Массивы могут быть вложенными
matrix = [[1, 2], [3, 4]]

# Типы внутри одного массива можно смешивать (TOML 1.0)
mixed = [1, "два", 3.0, true]

Массивы таблиц

Двойные квадратные скобки [[name]] создают массив таблиц — каждый такой заголовок добавляет новый элемент списка.

# Каждый блок [[products]] — отдельный элемент массива
[[products]]
name = "Молоток"
sku = 738594937

[[products]]
name = "Гвоздь"
sku = 284758393
color = "серый"

# В итоге получится:
# products = [
#   { name = "Молоток", sku = 738594937 },
#   { name = "Гвоздь",  sku = 284758393, color = "серый" },
# ]

# Массивы таблиц можно вкладывать друг в друга
[[fruits]]
name = "яблоко"

  [[fruits.varieties]]    # вложенный массив внутри элемента fruits
  name = "антоновка"

  [[fruits.varieties]]
  name = "гала"

Inline-таблицы

# Inline-таблица — компактная запись таблицы в фигурных скобках,
# целиком на одной строке. Удобна для коротких сгруппированных значений.
point = { x = 1, y = 2 }

server = { host = "localhost", port = 5432, ssl = true }

# Значениями могут быть и массивы
range = { min = 0, max = 100, steps = [10, 20, 30] }

# Правила: всё в одной строке, нельзя дополнять её позже
# отдельными ключами или заголовком [server.x].

Сравнение с JSON и YAML

# TOML против соседей по конфигам:
#
# JSON — машинно-строгий, но многословный: кавычки у каждого ключа,
#        нет комментариев, легко промахнуться с запятой.
#
# YAML — лаконичный, но отступы значимы: лишний пробел ломает файл,
#        а неявные правила типов дают сюрпризы (norway-problem:
#        no превращается в false).
#
# TOML — золотая середина: комментарии есть, отступы не важны,
#        типы явные, структура читается сверху вниз.
#        Минус — для глубоко вложенных деревьев многословнее YAML.
#
# Один и тот же конфиг:
# JSON:  { "server": { "port": 8080 } }
# YAML:  server:\n  port: 8080
# TOML:  [server]\n  port = 8080

Практический пример: pyproject.toml

Соберём всё вместе на живом конфиге Python-проекта — здесь встречаются таблицы, вложенные таблицы, массивы и массивы таблиц.

# --- система сборки (PEP 518) ---
[build-system]
requires = ["hatchling"]            # массив строк-зависимостей
build-backend = "hatchling.build"

# --- метаданные проекта (PEP 621) ---
[project]
name = "codechick"
version = "1.0.0"
description = "Учебная платформа"
requires-python = ">=3.11"
readme = "README.md"
keywords = ["education", "python", "toml"]

# Список зависимостей пакета
dependencies = [
  "django>=5.0",
  "requests>=2.31",
]

# Авторы — массив inline-таблиц
authors = [
  { name = "Эрнест", email = "[email protected]" },
]

# Опциональные группы зависимостей (вложенная таблица)
[project.optional-dependencies]
dev = ["pytest>=8.0", "ruff"]

# Ссылки проекта
[project.urls]
Homepage = "https://codechick.io"

# --- конфиг инструмента (линтер ruff) ---
[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I"]            # включённые наборы правил
ignore = ["E501"]                  # игнорируемые проверки