TOML Python Integration

Work with TOML configuration files using the tomlkit library, which preserves comments and formatting during read-modify-write cycles.

When to Use This Skill

Use this skill when:

• Reading or writing TOML configuration files (config.toml, pyproject.toml)
• Modifying existing TOML files while preserving comments and formatting
• Parsing TOML into Python data structures
• Creating TOML documents programmatically
• Handling TOML syntax errors and validation
• Implementing config file management for Python applications
• Working with XDG Base Directory specification for config locations

Core Capabilities

Library Selection: tomlkit vs tomllib

Use tomlkit when:

• Modifying existing config files (preserves comments and formatting)
• Building applications that write configuration
• Need single library for both reading and writing
• Python 3.8+ compatibility required

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
try:
    doc = tomlkit.parse(toml_string)
except ParseError as e:
    print(f"Parse error at line {e.line}, column {e.col}: {e}")

# Handle missing keys
try:
    value = doc["nonexistent"]
except (KeyError, NonExistentKey):
    value = "default"

# Handle file not found
try:
    with open("config.toml", "r") as f:
        doc = tomlkit.load(f)
except FileNotFoundError:
    # Create default config
    doc = create_default_config()

Common Patterns

Pattern 1: Load or Create Config

import tomlkit
from pathlib import Path


def load_or_create_config(path: Path) -> tomlkit.TOMLDocument:
    """Load existing config or create default if missing."""
    if path.exists():
        with open(path, "r") as f:
            return tomlkit.load(f)

    # Create default
    doc = tomlkit.document()
    doc.add(tomlkit.comment("Default configuration"))
    doc.add(tomlkit.nl())

    doc["app"] = tomlkit.table()
    doc["app"]["name"] = "myapp"
    doc["app"]["version"] = "1.0.0"

    path.parent.mkdir(parents=True, exist_ok=True)
    with open(path, "w") as f:
        tomlkit.dump(doc, f)

    return doc

Pattern 2: Update Single Value (Preserving Comments)

import tomlkit


def update_config_value(path: str, section: str, key: str, value):
    """Update single value while preserving all comments."""
    with open(path, "r") as f:
        doc = tomlkit.load(f)

    if section not in doc:
        doc[section] = tomlkit.table()

    doc[section][key] = value

    with open(path, "w") as f:
        tomlkit.dump(doc, f)


# Usage
update_config_value("config.toml", "database", "port", 5433)

Pattern 3: Atomic Updates

import tomlkit
from pathlib import Path
import tempfile
import shutil


def atomic_config_update(path: Path, updates: dict):
    """Update config atomically to prevent corruption."""
    with open(path, "r") as f:
        doc = tomlkit.load(f)

    # Apply updates
    for section, values in updates.items():
        if section not in doc:
            doc[section] = tomlkit.table()
        for key, value in values.items():
            doc[section][key] = value

    # Write to temp file, then atomic move
    temp_fd, temp_path = tempfile.mkstemp(suffix=".toml")
    try:
        with open(temp_fd, "w") as f:
            tomlkit.dump(doc, f)
        shutil.move(temp_path, path)
    except Exception:
        Path(temp_path).unlink(missing_ok=True)
        raise

Pattern 4: Config Validation

import tomlkit
from tomlkit.exceptions import ParseError


def validate_config(path: str) -> tuple[bool, str]:
    """Validate config structure. Returns (is_valid, error_message)."""
    try:
        with open(path, "r") as f:
            doc = tomlkit.load(f)
    except FileNotFoundError:
        return False, "Config file not found"
    except ParseError as e:
        return False, f"Invalid TOML at line {e.line}, col {e.col}"

    required_sections = ["app", "database"]
    missing = [s for s in required_sections if s not in doc]

    if missing:
        return False, f"Missing sections: {', '.join(missing)}"

    if "name" not in doc.get("app", {}):
        return False, "Missing required key: app.name"

    return True, ""

XDG Base Directory Integration

For config file locations following XDG specification, activate the xdg-base-directory skill:

Skill(skill: "xdg-base-directory:xdg-base-directory")

Standard config path pattern:

from pathlib import Path


def get_config_path(app_name: str) -> Path:
    """Get XDG-compliant config path."""
    config_dir = Path.home() / ".config" / app_name
    return config_dir / "config.toml"


# Usage
config_path = get_config_path("myapp")
# Returns: ~/.config/myapp/config.toml

TOML Syntax Quick Reference

Basic Types

# Strings
string = "Hello, World!"
multiline = """
Multiple
lines
"""
literal = 'C:\path\no\escaping'

# Numbers
integer = 42
float = 3.14
scientific = 1e10

# Boolean
flag = true

# Date/Time
datetime = 2024-01-15T10:30:00Z
date = 2024-01-15
time = 10:30:00

Tables and Arrays

# Standard table
[database]
host = "localhost"
port = 5432

# Nested table
[database.pool]
max_connections = 100

# Inline table
point = { x = 1, y = 2 }

# Array
numbers = [1, 2, 3]

# Array of tables
[[products]]
name = "Widget"
price = 9.99

[[products]]
name = "Gadget"
price = 19.99

Type Mappings

TOML Type	Python Type
String	str
Integer	int
Float	float
Boolean	bool
Offset Date-Time	datetime.datetime
Local Date-Time	datetime.datetime
Local Date	datetime.date
Local Time	datetime.time
Array	list
Table	dict

Key Features of tomlkit

Comment Preservation

import tomlkit

original = """
# Configuration file
[database]
# Database host
host = "localhost"
# Database port
port = 5432
"""

doc = tomlkit.parse(original)
doc["database"]["port"] = 5433

result = tomlkit.dumps(doc)
# Comments are preserved in result

Reason: User-added comments in config files should survive application updates.

Format Preservation

tomlkit maintains:

• Original indentation
• Whitespace patterns
• Key ordering
• Comment placement
• Quote style preferences

Reason: Minimal diffs in version control when config changes.

Table Creation Helpers

from tomlkit import document, table

doc = document()

# Regular table
config = table()
config["key"] = "value"
doc["config"] = config

# Super table (parent of nested tables)
parent = table(is_super_table=True)
child = table()
child["x"] = 1
parent.append("child", child)
doc.append("parent", parent)

print(doc.as_string())
# [parent.child]
# x = 1

Common Pitfalls

Issue: Losing Comments

# ❌ Wrong: Using unwrap() loses formatting
doc = tomlkit.load(f)
pure_dict = doc.unwrap()
# Modifications to pure_dict lose all comments

# ✓ Correct: Modify doc directly
doc = tomlkit.load(f)
doc["section"]["key"] = "value"
# Comments preserved

Issue: Type Mismatches

# ❌ Wrong: Assuming types
value = doc["port"]  # Might be string or int

# ✓ Correct: Validate types
port = doc["port"]
if not isinstance(port, int):
    raise ValueError(f"Expected int for port, got {type(port)}")

Issue: Missing Keys

# ❌ Wrong: Direct access without checking
value = doc["section"]["key"]  # KeyError if missing

# ✓ Correct: Use .get() with defaults
value = doc.get("section", {}).get("key", "default")

Configuration File Example

# ~/.config/myapp/config.toml
# Application configuration

[app]
# Application name
name = "myapp"
# Application version
version = "1.0.0"
# Debug mode
debug = false

[database]
# Database connection settings
host = "localhost"
port = 5432
name = "myapp_db"
pool_size = 10

[logging]
# Logging configuration
level = "INFO"
file = "/var/log/myapp/app.log"
max_size_mb = 100

[features]
# Feature flags
enable_api = true
enable_web = true
enable_workers = false

Dataclass Integration Pattern

from dataclasses import dataclass
import tomlkit
from pathlib import Path


@dataclass
class AppConfig:
    name: str
    version: str
    debug: bool = False


@dataclass
class DatabaseConfig:
    host: str
    port: int
    name: str
    pool_size: int = 10


@dataclass
class Config:
    app: AppConfig
    database: DatabaseConfig


def load_config(path: Path) -> Config:
    """Load TOML config into dataclasses."""
    with open(path, "r") as f:
        data = tomlkit.load(f)

    return Config(app=AppConfig(**data.get("app", {})), database=DatabaseConfig(**data.get("database", {})))


def save_config(config: Config, path: Path):
    """Save dataclasses to TOML, preserving existing comments."""
    if path.exists():
        with open(path, "r") as f:
            doc = tomlkit.load(f)
    else:
        doc = tomlkit.document()

    # Update from dataclasses
    if "app" not in doc:
        doc["app"] = tomlkit.table()
    doc["app"]["name"] = config.app.name
    doc["app"]["version"] = config.app.version
    doc["app"]["debug"] = config.app.debug

    if "database" not in doc:
        doc["database"] = tomlkit.table()
    doc["database"]["host"] = config.database.host
    doc["database"]["port"] = config.database.port
    doc["database"]["name"] = config.database.name
    doc["database"]["pool_size"] = config.database.pool_size

    path.parent.mkdir(parents=True, exist_ok=True)
    with open(path, "w") as f:
        tomlkit.dump(doc, f)

References

Official Documentation

• tomlkit Documentation - Complete API reference
• tomlkit PyPI - Package information
• tomlkit GitHub - Source code
• TOML Specification - TOML v1.0.0 specification
• Python tomllib - Stdlib alternative (read-only)

Related Skills

• xdg-base-directory - For XDG-compliant config file locations
• standards-for-python-development - For the shared Python rules
• uv - For dependency management

Tools

• tomlkit - Comment-preserving TOML library (read/write)
• tomllib - Stdlib TOML parser (read-only, Python 3.11+)
• tomli_w - Stdlib-compatible TOML writer