{"id":6348,"library":"dom-toml","title":"dom-toml","description":"dom-toml is a Python library providing tools for parsing and writing Tom's Obvious, Minimal Language (TOML) files. It offers functionalities for both loading TOML data from strings or files into Python dictionaries and dumping Python data structures back into TOML format. The library is actively maintained, with frequent releases addressing features and compatibility, and the current version is 2.3.0.","status":"active","version":"2.3.0","language":"en","source_language":"en","source_url":"https://github.com/domdfcoding/dom_toml","tags":["toml","configuration","parser","serializer","config","domdfcoding"],"install":[{"cmd":"pip install dom-toml","lang":"bash","label":"Install stable version"},{"cmd":"pip install dom-toml[config]","lang":"bash","label":"Install with config module support"}],"dependencies":[{"reason":"Required for the 'config' module which provides structured configuration classes.","package":"attrs","optional":true}],"imports":[{"symbol":"load","correct":"from dom_toml import load"},{"symbol":"loads","correct":"from dom_toml import loads"},{"symbol":"dump","correct":"from dom_toml import dump"},{"symbol":"dumps","correct":"from dom_toml import dumps"},{"note":"For structured configuration parsing (requires 'config' extra).","symbol":"Config","correct":"from dom_toml.config import Config"}],"quickstart":{"code":"import os\nfrom dom_toml import loads, dumps\n\n# Example TOML string\ntoml_data_str = \"\"\"\n[project]\nname = \"my-package\"\nversion = \"0.1.0\"\nauthors = [\n    { name = \"Alice\", email = \"alice@example.com\" },\n    { name = \"Bob\", email = \"bob@example.com\" }\n]\n\"\"\"\n\n# Load TOML from a string\nconfig = loads(toml_data_str)\nprint(\"Loaded TOML:\", config)\n# Expected: {'project': {'name': 'my-package', 'version': '0.1.0', 'authors': [{'name': 'Alice', 'email': 'alice@example.com'}, {'name': 'Bob', 'email': 'bob@example.com'}]}}\n\n# Modify data (optional)\nconfig['project']['license'] = 'MIT'\n\n# Dump Python dict to TOML string\nupdated_toml_str = dumps(config)\nprint(\"\\nUpdated TOML string:\\n\", updated_toml_str)\n\n# Example of writing to a file (requires a temporary file)\nimport tempfile\nwith tempfile.NamedTemporaryFile(mode='w+', delete=False, suffix='.toml') as tmp_file:\n    tmp_file_name = tmp_file.name\n    dump(config, tmp_file_name)\n\nprint(f\"\\nTOML written to {tmp_file_name}. Contents:\\n\")\nwith open(tmp_file_name, 'r') as f:\n    print(f.read())\n\n# Clean up temporary file\nos.remove(tmp_file_name)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always open TOML files in binary mode: `with open('config.toml', 'rb') as f: config = load(f)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions (TOML specification)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}