Tomli-W: A Minimal TOML Writer

Warnings

• breaking `tomli-w` requires Python 3.9 or newer. Attempts to use it on older Python versions will result in an `ImportError` or `SyntaxError`.
  Fix: Ensure your Python environment is 3.9 or newer. Consider `tomllib` (Python 3.11+) or `tomlkit` for broader compatibility needs if you need a writer for older Python versions.
• gotcha `tomli-w` does not preserve comments, original ordering (beyond respecting input dictionary order), or custom whitespace. For style-preserving writing (e.g., maintaining comments, specific indentation), `tomlkit` is a recommended alternative.
  Fix: If style preservation is critical, evaluate `tomlkit`. Otherwise, ensure your workflow does not depend on output TOML mirroring input formatting precisely.
• gotcha The library does not automatically validate the generated TOML. If the input data contains non-standard types or structures that could result in invalid TOML (e.g., objects whose `__str__` method produces invalid TOML syntax), `tomli-w` will write it without raising an error. It's recommended to validate the output by parsing it with a TOML reader like `tomli.loads()` (or `tomllib.loads()` in Python 3.11+).
  Fix: After writing, parse the generated TOML string or file content with `tomli.loads()` within a `try-except tomli.TOMLDecodeError` block to ensure validity, especially if the input data source is untrusted or complex.
• gotcha When writing TOML to a file using `tomli_w.dump()`, the file must be opened in binary write mode (`'wb'`). Using text mode (`'w'`) can lead to encoding issues (e.g., incorrect UTF-8 handling) or incorrect newline handling.
  Fix: Always open files with `mode='wb'` when using `tomli_w.dump()`: `with open('config.toml', 'wb') as f: tomli_w.dump(data, f)`.
• gotcha By default, `tomli-w` avoids writing multi-line strings (using triple quotes in TOML) even if the Python string value contains newlines. This design choice aims to ensure lossless parse/write round-trips for TOML strings where exact byte representation matters.
  Fix: Be aware that strings with newlines will be output as single-line TOML strings with escaped newline characters (e.g., `\n`). If multi-line visual representation is strictly required, manual string formatting before passing to `tomli_w` or using `tomlkit` might be necessary.
• gotcha `tomli-w` is exclusively for writing TOML and does not provide any functionality for parsing or reading TOML documents.
  Fix: For reading TOML, use the `tomli` library (for Python <3.11) or Python's built-in `tomllib` module (for Python 3.11+).

Install

• pip install tomli-w Install with pip

Imports

• tomli_w

  import tomli_w

  Provides `dump()` for writing to files and `dumps()` for writing to strings.

Quickstart

This example demonstrates how to write a Python dictionary to a TOML formatted string using `tomli_w.dumps()` and how to write it directly to a file using `tomli_w.dump()`. It includes a cleanup step to remove the generated file.

import tomli_w
import os

# Example data to write
doc = {
    "title": "My Awesome Project",
    "owner": {
        "name": "Alice Example",
        "organization": "Example Corp",
        "dob": "1979-05-27T07:32:00-08:00"
    },
    "database": {
        "server": "192.168.1.1",
        "ports": [8001, 8001, 8002],
        "connection_max": 5000,
        "enabled": True
    },
    "servers": {
        "alpha": {
            "ip": "10.0.0.1",
            "dc": "eqdc10"
        },
        "beta": {
            "ip": "10.0.0.2",
            "dc": "eqdc10"
        }
    }
}

# 1. Write to a string
toml_string = tomli_w.dumps(doc)
print("--- TOML String ---")
print(toml_string)

# 2. Write to a file
file_path = "config.toml"
try:
    with open(file_path, "wb") as f:
        tomli_w.dump(doc, f)
    print(f"\n--- TOML written to {file_path} ---")
    with open(file_path, "r") as f_read:
        print(f_read.read())
except Exception as e:
    print(f"Error writing TOML to file: {e}")
finally:
    if os.path.exists(file_path):
        os.remove(file_path) # Clean up