tomlkit

tomlkit is a 1.1.0-compliant TOML library for Python built around a core idea most parsers ignore: round-tripping a document should not destroy how a human wrote it. Parsing a file with tomlkit produces a tree of typed items that remember their original comments, indentation, and key ordering, so editing a single value and re-serializing the document yields a diff limited to that value instead of a fully reformatted file. It also exposes helpers for building brand-new TOML documents programmatically from plain Python values.

Originally built for the Poetry package manager to safely edit pyproject.toml files, tomlkit has become the de facto choice anywhere a tool needs to read and rewrite TOML config without clobbering a user’s formatting choices - dependency managers, linters, and CLI scaffolding tools among them.

What You Get

• A style-preserving parser (tomlkit.parse / tomlkit.load) that retains comments, whitespace, and item ordering
• A TOMLDocument object model with typed items (Table, Array, InlineTable, DateTime, etc.) that mirror TOML’s grammar
• Builder helpers (tomlkit.document, tomlkit.table, tomlkit.array, item()) for constructing new documents from scratch
• Full TOML 1.1.0 compliance validated against the upstream toml-test conformance suite
• A dict-like API (__getitem__/__setitem__, .unwrap()) so documents can be used like ordinary Python mappings

Common Use Cases

• Programmatically editing pyproject.toml or similar config files during automated dependency or version bumps without rewriting the whole file
• Building CLI tools (like Poetry) that read a TOML config, change one field, and save it back with the user’s original formatting untouched
• Converting Python data structures into new, well-formatted TOML documents for generated configuration
• Validating or migrating TOML files against the 1.1.0 spec as part of a linting or codemod pipeline

Under The Hood

Architecture - tomlkit’s core is a layered document model: source.py implements a cursor-based character reader, parser.py walks that stream into a Container (container.py), which holds an ordered mapping of Key objects to Item instances defined in items.py (Table, Array, InlineTable, String, DateTime, etc.). Every item stores its own Trivia (leading comment/whitespace) alongside its value, which is what lets TOMLDocument.as_string() reconstruct byte-for-byte output for anything the user didn’t touch. api.py is the thin public surface (parse, dumps, load, document, table, array, item) that wires these pieces together into the functions users actually call. Tech Stack - Pure Python with no runtime dependencies, targeting Python 3.9+; the project uses Poetry for packaging, ruff for linting (with isort, bugbear, comprehensions rule sets), mypy in strict mode for type-checking, and Sphinx/furo for documentation. Code Quality - The tests/ directory covers parser edge cases, item construction, document round-tripping, and file I/O (test_parser.py, test_items.py, test_toml_document.py, test_build.py, test_write.py), plus a dedicated test_toml_tests.py that runs the project against the language-agnostic toml-test submodule for spec conformance; mypy strict mode and typed _types.py definitions give the codebase consistent typing throughout. API Design - The public API is intentionally small and mirrors Python’s built-in json/toml module conventions (loads/dumps/load/dump), so anyone familiar with stdlib serialization modules can be productive immediately, while power users can drop into the typed item tree for fine-grained document construction.