Toml Python

Use tomllib (stdlib) when:

• Python 3.11+ only
• Read-only access sufficient (no writing capability)
• Minimal dependencies preferred

For config file management, tomlkit is the recommended choice.

Installation

# Using uv (recommended)
uv add tomlkit

# Using pip
pip install tomlkit

Requirements: Python >=3.8, tomlkit >=0.12.0

tomlkit API Reference

Reading TOML

import tomlkit

# From string
doc = tomlkit.parse(toml_string)
doc = tomlkit.loads(toml_string)  # Alias for parse()

# From file object
with open('config.toml', 'r') as f:
    doc = tomlkit.load(f)

# Using TOMLFile class (convenient)
from tomlkit import TOMLFile

toml_file = TOMLFile('config.toml')
doc = toml_file.read()

Returns: TOMLDocument object (dict-like, preserves formatting)

Writing TOML

import tomlkit

# To string
toml_string = tomlkit.dumps(data)

# To file object
with open('config.toml', 'w') as f:
    tomlkit.dump(data, f)

# Using TOMLFile class
from tomlkit import TOMLFile

toml_file = TOMLFile('config.toml')
toml_file.write(doc)

Creating TOML Documents

from tomlkit import document, table, comment, nl, array, inline_table

# Create document
doc = document()
doc.add(comment("Configuration file"))
doc.add(nl())
doc.add("title", "My Config")

# Create table
db_config = table()
db_config["host"] = "localhost"
db_config["port"] = 5432
doc["database"] = db_config

# Create inline table
point = inline_table()
point.update({'x': 1, 'y': 2})
doc["point"] = point

# Create array
numbers = array()
numbers.extend([1, 2, 3])
doc["numbers"] = numbers

Document Manipulation

# Dict-like access
doc["section"]["key"] = "value"
value = doc["section"]["key"]

# Get with default
value = doc.get("key", "default")

# Check existence
if "key" in doc:
    pass

# Iterate
for key, value in doc.items():
    print(key, value)

# Remove key
doc.pop("key")
doc.remove("key")

# Convert to pure Python dict
pure_dict = doc.unwrap()

# Get as TOML string
toml_str = doc.as_string()

Value Creation Helpers

from tomlkit import (
    item,          # Auto-detect type
    string,        # String with options
    integer,       # Integer
    float_,        # Float
    boolean,       # Boolean
    datetime,      # Datetime
    date,          # Date
    time,          # Time
)

# Auto-detect type
doc["key"] = item(42)
doc["key"] = item([1, 2, 3])
doc["key"] = item({'nested': 'table'})

# Explicit string types
doc["basic"] = string("text")
doc["literal"] = string("text", literal=True)  # Single quotes
doc["multiline"] = string("line1\nline2", multiline=True)

Error Handling

Exception Types

from tomlkit.exceptions import (
    TOMLKitError,           # Base exception
    ParseError,             # Syntax errors (has .line and .col)
    NonExistentKey,         # Missing key access
    KeyAlreadyPresent,      # Duplicate key
    ConvertError,           # Type conversion failure
)

# Handle parse errors