tomlkit

I've used tomlkit extensively for configuration management where preserving comments and formatting matters. Unlike standard toml libraries, it maintains the exact structure of your TOML files when you parse and modify them, which is invaluable for CLI tools that need to programmatically edit user configs without destroying their careful formatting.

From a security perspective, tomlkit is refreshingly minimal with zero dependencies beyond the Python standard library, which dramatically reduces supply chain risk. The parsing is strict and follows TOML spec closely, rejecting malformed input cleanly with informative exceptions. Error messages don't leak system paths or internal state. I haven't seen any CVEs against it, and the codebase is small enough to audit yourself if needed.

The API is straightforward - load(), dump(), and dict-like access. Input validation happens automatically during parsing with proper boundary checks. No cryptographic operations means no TLS/crypto concerns. The main limitation is performance on very large TOML files (multi-MB), where it's noticeably slower than rust-based parsers, but for typical config files it's perfectly adequate.

I've used tomlkit extensively for building CLI tools that need to modify pyproject.toml and other config files without destroying user formatting. The core API is straightforward - parse() to read, then manipulate the resulting dict-like object, and dumps() to write back. What sets it apart from standard tomllib is that comments, whitespace, and formatting are preserved perfectly, which is crucial for automated tooling.

The learning curve is gentle if you've used any TOML parser before. The documentation is sparse but the API is intuitive enough that you can figure out most operations from the type hints and a few examples. Error messages are decent - when you hit malformed TOML, you get line numbers and clear descriptions. One gotcha: the objects returned aren't plain dicts, they're special wrapper types, which occasionally causes isinstance() checks to fail.

Debugging is mostly painless. The biggest challenge is understanding when tomlkit creates inline tables vs regular tables, but this only matters if you're programmatically generating complex structures. For reading and modifying existing files, it just works.

Tomlkit shines when you need to programmatically edit TOML files while preserving comments, whitespace, and formatting - something the standard `tomli` library can't do. The parsing is straightforward with `tomlkit.load()` and `tomlkit.loads()`, but the returned objects aren't plain dicts. They're special container types that maintain style information, which trips you up initially.

The learning curve is moderate because error messages can be cryptic when you try dict operations that don't work on tomlkit objects. You'll find yourself debugging type issues (`tomlkit.items.Integer` vs `int`) more than you'd like. The documentation exists but lacks comprehensive examples for common scenarios like manipulating nested tables or handling arrays properly. Stack Overflow coverage is thin, so expect to read the source code occasionally.

Once you understand the mental model - that you're working with a structured document rather than plain data - it becomes predictable. For simple read-modify-write workflows on config files, it works reliably. The `unwrap()` method helps when you need plain Python types for further processing.