• TOML: Tom's Obvious Minimal Language
• TOML Schema Validation

[user]
player_x.color = "blue"
player_o.color = "green"

[constant]
board_size = 3

[server]
url = "https://tictactoe.example.com"

• all keys are interpreted as strings
• TOML has no null type
• Some whitespace is important
  makes it less efficient to compress the size of TOML documents.

match config:
    case {
        "user": {"player_x": {"color": str()}, "player_o": {"color": str()}},
        "constant": {"board_size": int()},
        "server": {"url": str()},
    }:
        pass
    case _:
        raise ValueError(f"invalid configuration: {config}")

• Strings, Numbers, and Booleans
• Tables
• Times and Dates
• Arrays

• String
• Integer
• Float
• Boolean
• Offset date-time
• Local date-time
• Local date
• Local time
• Array
• Inline table

can avoid the limits of bare keys by using Unicode strings as keys
generally want to use bare keys

dots (.) play a special role in TOML keys
can use dots in unquoted keys
in that case, they'll trigger grouping by splitting the dotted key at each dot

player_x.symbol = "X"
player_x.color = "purple"

a TOML string should typically use double quotation marks (")
inside strings can escape special characters with the help of backslashes

"\u03c0 is less than four"

can also specify TOML strings using single quotation marks (')
single-quoted strings are called literal strings and behave similarly to raw strings in Python
nothing is escaped and interpreted in a literal string
'\u03c0 is the Unicode codepoint of π' starts with the literal \u03c0 characters

'\u03c0 is the Unicode codepoint of π'

partly_zen = """
Flat is better than nested.
Sparse is better than dense.
"""

'''Use '\u03c0' to represent π'''

numbers = "one\ntwo\nthree"

>>> 'numbers = "one\ntwo\nthree"'
'numbers = "one\ntwo\nthree"'

>>> r'numbers = "one\ntwo\nthree"'
'numbers = "one\\ntwo\\nthree"'

number = 42
negative = -8
large = 60_481_729

number = 3.11
googol = 1e100
mole = 6.22e23
negative_infinity = -inf
not_a_number = nan

non-negative integer values may also be represented as hexadecimal, octal, or binary values by using a 0x, 0o, or 0b prefix, respectively

TOML supports three different ways of specifying tables
the different tables do have slightly different use cases

• use regular tables with headers in most cases
• use dotted key tables when need to specify a few key-value pairs
  pairs are closely tied to their parent table
• use inline tables only for very small tables with up to three key-value pairs
  the data makes up a clearly defined entity.

regular tables are defined by adding a table header above the key-value pairs
a header is a key without a value, wrapped inside square brackets ([])
three tables

[user]
player_x.color = "blue"
player_o.color = "green"

[constant]
board_size = 3

[server]
url = "https://tictactoe.example.com"

[user]
player_x.color = "blue"
player_o.color = "green"

[user]

    [user.player_x]
    color = "blue"

    [user.player_o]
    color = "green"

table examples

# nested regular tables
[user]

    [user.player_x]
    symbol = "X"
    color = "blue"

    [user.player_o]
    symbol = "O"
    color = "green"

# nested dotted key tables
[user]
player_x.symbol = "X"
player_x.color = "blue"
player_o.symbol = "O"
player_o.color = "green"

# inline table
[user]
player_x = { symbol = "X", color = "blue" }
player_o = { symbol = "O", color = "green" }

a TOML document is represented by a nameless root table that contains all other tables and key-value pairs
key-value pairs written at the top of the TOML configuration (before any table header) are stored directly in the root table

title = "Tic-Tac-Toe"

[constant]
board_size = 3

[user]

    [user.player_x]
    color = "blue"

    [user.player_o]
    color = "green"

background_color = "white"

• offset date-time - a timestamp with time zone information
  representing a specific instant in time
• local date-time - a timestamp without time zone information
• local date - a date without any time zone information
  typically used to represent a full day
• local time - a time with any date or time zone information
  use a local time to represent a time of day

2021-01-12T01:23:45.654321+01:00

the microsecond field is optional for all date-time and time types
can replace the T that separates the date and time with a space
examples of each of the timestamp-related types

offset_date-time     = 2021-01-12 01:23:45+01:00
offset_date-time_utc = 2021-01-12 00:23:45Z
local_date-time      = 2021-01-12 01:23:45
local_date           = 2021-01-12
local_time           = 01:23:45
local_time_with_us   = 01:23:45.654321

packages = ["tomllib", "tomli", "tomli_w", "tomlkit"]

potpourri = ["flower", 1749, { symbol = "X", color = "blue" }, 1994-02-14]
skiers = ["Thomas", "Bjørn", "Mika"]
players = [
    { symbol = "X", color = "blue", ai = true },
    { symbol = "O", color = "green", ai = false },
]

[[players]]
symbol = "X"
color = "blue"
ai = true

[[players]]
symbol = "O"
color = "green"
ai = false

[python]
label = "Python"

[[python.questions]]
question = "Which built-in function can get information from the user"
answers = ["input"]
alternatives = ["get", "print", "write"]

[[python.questions]]
question = "What's the purpose of the built-in zip() function"
answers = ["To iterate over two or more sequences at the same time"]
alternatives = [
    "To combine several strings into one",
    "To compress several files into one archive",
    "To get information from the user",
]

• label
• questions

• question
• answers
• alternatives

• Read TOML Documents With tomli and tomllib
• Compare TOML Types and Python Types
• Use Configuration Files in Projects

# tic_tac_toe.toml

[user]
player_x.color = "blue"
player_o.color = "green"

[constant]
board_size = 3

[server]
url = "https://tictactoe.example.com"

(venv) $ python -m pip install tomli

• load() - loads a TOML doc from a file
• loads() - loads a TOML doc from a string

>>> import tomli
>>> with open("tic_tac_toe.toml", mode="rb") as fp:
...     config = tomli.load(fp)
...
>>> config
{'user': {'player_x': {'color': 'blue'}, 'player_o': {'color': 'green'}},
 'constant': {'board_size': 3},
 'server': {'url': 'https://tictactoe.example.com'}}

>>> config["user"]["player_o"]
{'color': 'green'}

>>> config["server"]["url"]
'https://tictactoe.example.com'

if the TOML document is represented as a string, then use loads()
the 's' in loads() stands for string

>>> import tomli
>>> toml_str = """
... offset_date-time_utc = 2021-01-12 00:23:45Z
... potpourri = ["flower", 1749, { symbol = "X", color = "blue" }, 1994-02-14]
... """

>>> tomli.loads(toml_str)
{'offset_date-time_utc': datetime.datetime(2021, 1, 12, 0, 23, 45, tzinfo=datetime.timezone.utc),
 'potpourri': ['flower',
               1749,
               {'symbol': 'X', 'color': 'blue'},
               datetime.date(1994, 2, 14)]}

• a TOML file must be a valid UTF-8 encoded Unicode document
• arbitrary 64-bit signed integers (from −2^63 to 2^63−1) should be accepted and handled losslessly
• floats should be implemented as IEEE 754 binary64 values

in the folder where tic-tac-toe.toml is located and add a subfolder named config

# tic_tac_toe.toml

[user]
player_x.color = "blue"
player_o.color = "green"

[constant]
board_size = 3

[server]
url = "https://tictactoe.example.com"

config/
├── __init__.py
└── tic_tac_toe.toml

# __init__.py

import pathlib
import tomli

path = pathlib.Path(__file__).parent / "tic_tac_toe.toml"
with path.open(mode="rb") as fp:
    tic_tac_toe = tomli.load(fp)

>>> import config
>>> config.path
PosixPath('/home/realpython/config/tic_tac_toe.toml')

>>> config.tic_tac_toe
{'user': {'player_x': {'color': 'blue'}, 'player_o': {'color': 'green'}},
 'constant': {'board_size': 3},
 'server': {'url': 'https://tictactoe.example.com'}}

>>> config.tic_tac_toe["server"]["url"]
'https://tictactoe.example.com'

>>> config.tic_tac_toe["constant"]["board_size"]
3

>>> config.tic_tac_toe["user"]["player_o"]
{'color': 'green'}

>>> config.tic_tac_toe["user"]["player_o"]["color"]
'green'

from config import tic_tac_toe as CFG

color_x = CFG["user"]["player_x"]["color"]

• Convert Dictionaries to TOML
• Write TOML Documents With tomli_w

_dumps_value() is a helper function
takes a value and return its TOML representation based on the value type
uses pattern matching for type checking

# to_toml.py

def _dumps_value(value):
    match value:
        case bool() : return "true" if value else "false"         
        case float() : return str(value)
        case int() : return str(value)
        case str() : return f'"{value}"'
        case list() : return f"[{', '.join(_dumps_value(v) for v in value)}]"
        case _ : raise TypeError(f"{type(value).__name__} {value!r} is not supported")

dumps() parses the dictionary converting each item to a key-value pair
if an item is another dictionary the dumps() function recurses on itself
add this method to to_toml.py

def dumps(toml_dict, table=""):
    def tables_at_end(item):
        _, value = item
        return isinstance(value, dict)

    toml = []
    for key, value in sorted(toml_dict.items(), key=tables_at_end):
        if isinstance(value, dict):
            table_key = f"{table}.{key}" if table else key
            toml.append(f"\n[{table_key}]\n{dumps(value, table_key)}")
        else:
            toml.append(f"{key} = {_dumps_value(value)}")
    return "\n".join(toml)

# toml_mule.py

import to_toml

config = {
    "user": {
        "player_x": {"symbol": "X", "color": "blue", "ai": True},
        "player_o": {"symbol": "O", "color": "green", "ai": False},
        "ai_skill": 0.85,
    },
    "board_size": 3,
    "server": {"url": "https://tictactoe.example.com"},
}

print(to_toml.dumps(config))

(venv) $ python -m pip install tomli_w

# tomli_w_mule.py

import tomli_w

config = {
    "user": {
        "player_x": {"symbol": "X", "color": "blue", "ai": True},
        "player_o": {"symbol": "O", "color": "green", "ai": False},
        "ai_skill": 0.85,
    },
    "board_size": 3,
    "server": {"url": "https://tictactoe.example.com"},
}

print(tomli_w.dumps(config))

dumps() writes to a string so processing can continue
to store the new TOML document directly to disk, then call dump() instead
as with load() need to pass in a file pointer opened in binary mode

>>> with open("tic-tac-toe-config.toml", mode="wb") as fp:
...     tomli_w.dump(config, fp)
...

>>> import tomli, tomli_w
>>> toml_data = """
... [nested]  # Not necessary
...
...     [nested.table]
...     string       = "Hello, TOML!"
...     weird_string = '''Literal
...         Multiline'''
... """
>>> print(tomli_w.dumps(tomli.loads(toml_data)))
[nested.table]
string = "Hello, TOML!"
weird_string = "Literal\n        Multiline"

• Format and Style TOML Documents
• Create TOML From Scratch With tomlkit

there's no style guide for TOML documents
some features in TOML are quite flexible

• can define tables in any order
• can even define a sub-table before its parent
• whitespace is ignored around keys
• the headers [nested.table] and [ nested . table] start the same nested table

(venv) $ python -m pip install tomlkit

>>> import tomlkit
>>> toml_data = """
... [nested]  # Not necessary
...
...     [nested.table]
...     string       = "Hello, TOML!"
...     weird_string = '''Literal
...         Multiline'''
... """
>>> print(tomlkit.dumps(tomlkit.loads(toml_data)))

[nested]  # Not necessary

    [nested.table]
    string       = "Hello, TOML!"
    weird_string = '''Literal
        Multiline'''

>>> tomlkit.dumps(tomlkit.loads(toml_data)) == toml_data
True

>>> from tomlkit import comment, document, nl, table

>>> toml = document()
>>> toml.add(comment("Written by TOML Kit"))
>>> toml.add(nl()) # empty line
>>> toml.add("board_size", 3)

>>> print(toml.as_string())
# Written by TOML Kit

board_size = 3

from tomlkit import comment, document, nl, table

toml = document()
toml.add(comment("Written by TOML Kit"))
toml.add(nl())
toml.add("board_size", 3)
player_x = table()
player_x.add("symbol", "X")
player_x.add("color", "blue")
player_x.comment("Start player")
toml.add("player_x", player_x)

player_o = table()
player_o.update({"symbol": "O", "color": "green"})
toml["player_o"] = player_o

print(toml.as_string())

• Represent TOML as tomlkit Objects
• Read and Write TOML Losslessly

# tic-tac-toe-config.toml

board_size = 3

[user]
ai_skill = 0.85  # A number between 0 (random) and 1 (expert)

    [user.player_x]
    symbol = "X"
    color = "blue"
    ai = true

    [user.player_o]
    symbol = "O"
    color = "green"
    ai = false

# Settings used when deploying the application
[server]
url = "https://tictactoe.example.com"

>>> import tomlkit
>>> with open("tic-tac-toe-config.toml", mode="rt", encoding="utf-8") as fp:
...     config = tomlkit.load(fp)
...
>>> config
{'board_size': 3, 'user': {'ai_skill': 0.85, 'player_x': { ... }}}

>>> type(config)
<class 'tomlkit.toml_document.TOMLDocument'>

a TOMLDocument works like a dictionary or a dictionary of dictionaries

>>> config["user"]["player_o"]["color"]
'green'

>>> type(config["user"]["player_o"]["color"])
<class 'tomlkit.items.String'>

>>> config["user"]["player_o"]["color"].upper()
'GREEN'

>>> config["user"]["ai_skill"]
0.85

>>> config["user"]["ai_skill"].trivia.comment
'# A number between 0 (random) and 1 (expert)'

>>> config["user"]["player_x"].trivia.indent
'    '

>>> config["board_size"] ** 2
9

>>> isinstance(config["board_size"], int)
True

>>> config["board_size"].unwrap()
3

>>> type(config["board_size"].unwrap())
<class 'int'>

>>> config.add("app_name", "Tic-Tac-Toe")
{'board_size': 3, 'app_name': 'Tic-Tac-Toe', 'user': { ... }}

>>> config["user"].add("ai_skill", 0.6)
Traceback (most recent call last):
  ...
KeyAlreadyPresent: Key "ai_skill" already exists.

>>> config["user"]["ai_skill"] = 0.6
>>> print(config["user"].as_string())
ai_skill = 0.6  # A number between 0 (random) and 1 (expert)

    [user.player_x]
    symbol = "X"
    color = "blue"
    ai = true

    [user.player_o]
    symbol = "O"
    color = "green"
    ai = false

>>> from tomlkit import aot, comment, inline_table, nl, table
>>> player_data = [
...     {"user": "gah", "first_name": "Geir Arne", "last_name": "Hjelle"},
...     {"user": "tompw", "first_name": "Tom", "last_name": "Preston-Werner"},
... ]

>>> players = aot()
>>> for player in player_data:
...     players.append(
...         table()
...         .add("username", player["user"])
...         .add("name",
...             inline_table()
...             .add("first", player["first_name"])
...             .add("last", player["last_name"])
...         )
...     )
...
>>> config.add(nl()).add(comment("Players")).add("players", players)