dom-toml

Warnings

• breaking In version 2.0.0, the `encoder` and `decoder` parameters for `dump`, `dumps`, `load`, and `loads` functions must now be instances or types of `dom_toml.encoder.TomlEncoder` or `dom_toml.decoder.TomlDecoder` respectively. Passing arbitrary callables is no longer supported directly.
  Fix: Ensure that custom encoders/decoders passed to the functions are subclasses or instances of the library's `TomlEncoder` or `TomlDecoder` classes. If you were passing a simple function, wrap it in a custom `TomlEncoder`/`TomlDecoder` subclass.
• gotcha When using `dom_toml.load()` with a file object, it is generally recommended to open the file in binary read mode (`'rb'`). This ensures correct handling of UTF-8 encoding and universal newlines, which is in line with the TOML specification.
  Fix: Always open TOML files in binary mode: `with open('config.toml', 'rb') as f: config = load(f)`.
• gotcha Unlike Python's built-in `tomllib` (Python 3.11+) or the `tomli` library, `dom-toml` is a separate implementation that provides both reading and writing capabilities. It does not use `tomli` or `tomllib` internally, meaning its behavior and features might differ slightly.
  Fix: Be aware that `dom-toml` offers its own unique set of features for TOML parsing and serialization beyond the standard `tomli`/`tomllib` API. Consult `dom-toml`'s documentation for specific functionalities and custom encoders/decoders.
• gotcha While TOML supports nested structures, excessively deep nesting or complex arrays of tables can become difficult to read and maintain. This is a general characteristic of the TOML format, not specific to `dom-toml`.
  Fix: Consider simplifying your TOML configuration schemas to minimize deep nesting and complex structures, especially for human-edited files. Utilize the `dom_toml.config` module for more structured Python-side handling of configurations if complexity is unavoidable.

Install

• pip install dom-toml Install stable version
• pip install dom-toml[config] Install with config module support

Imports

• load

  from dom_toml import load

• loads

  from dom_toml import loads

• dump

  from dom_toml import dump

• dumps

  from dom_toml import dumps

• Config

  from dom_toml.config import Config

  For structured configuration parsing (requires 'config' extra).

Quickstart

Demonstrates loading TOML from a string, modifying the resulting dictionary, and then dumping it back to a TOML string and writing it to a file. This covers the core read/write functionality.

import os
from dom_toml import loads, dumps

# Example TOML string
toml_data_str = """
[project]
name = "my-package"
version = "0.1.0"
authors = [
    { name = "Alice", email = "alice@example.com" },
    { name = "Bob", email = "bob@example.com" }
]
"""

# Load TOML from a string
config = loads(toml_data_str)
print("Loaded TOML:", config)
# Expected: {'project': {'name': 'my-package', 'version': '0.1.0', 'authors': [{'name': 'Alice', 'email': 'alice@example.com'}, {'name': 'Bob', 'email': 'bob@example.com'}]}}

# Modify data (optional)
config['project']['license'] = 'MIT'

# Dump Python dict to TOML string
updated_toml_str = dumps(config)
print("\nUpdated TOML string:\n", updated_toml_str)

# Example of writing to a file (requires a temporary file)
import tempfile
with tempfile.NamedTemporaryFile(mode='w+', delete=False, suffix='.toml') as tmp_file:
    tmp_file_name = tmp_file.name
    dump(config, tmp_file_name)

print(f"\nTOML written to {tmp_file_name}. Contents:\n")
with open(tmp_file_name, 'r') as f:
    print(f.read())

# Clean up temporary file
os.remove(tmp_file_name)