---
name: toml-python
description: Handles TOML configuration file operations in Python using tomlkit for comment-preserving read-modify-write cycles. Use when reading or writing pyproject.toml or any .toml config file, selecting between tomlkit and tomllib, modifying TOML while preserving comments and whitespace, implementing atomic config file updates, integrating TOML with Python dataclasses, handling TOML parse errors, or applying XDG base directory patterns for config file locations.
enabled: false
source: github:Jamie-BitFlight/claude_skills
imported-from: github:Jamie-BitFlight/claude_skills
---

# 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

```bash
# Using uv (recommended)
uv add tomlkit

# Using pip
pip install tomlkit
```

**Requirements:** Python >=3.8, tomlkit >=0.12.0

## tomlkit API Reference

### Reading TOML

```python
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

```python
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

```python
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

```python
# 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

```python
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

```python
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

```python
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)

```python
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

```python
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

```python
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:**

```python
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

```toml
# 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

```toml
# 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

```python
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

```python
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

```python
# ❌ 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

```python
# ❌ 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

```python
# ❌ 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

```toml
# ~/.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

```python
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](https://tomlkit.readthedocs.io/) - Complete API reference
- [tomlkit PyPI](https://pypi.org/project/tomlkit/) - Package information
- [tomlkit GitHub](https://github.com/sdispater/tomlkit) - Source code
- [TOML Specification](https://toml.io/en/) - TOML v1.0.0 specification
- [Python tomllib](https://docs.python.org/3.11/library/tomllib.html) - Stdlib alternative (read-only)

### Related Skills

- `xdg-base-directory` - For XDG-compliant config file locations
- `python3-development` - For Python development patterns
- `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
