toml

toml is a lightweight, pure-Python library for reading and writing TOML (Tom’s Obvious, Minimal Language) configuration files. It exposes a small, JSON-module-style API - load/loads for parsing and dump/dumps for serialization - making it a familiar drop-in for projects that already parse JSON or YAML.

Beyond the core encode/decode pair, the library ships pluggable encoder and decoder classes for handling edge cases: preserving key order, keeping inline comments, using custom array separators, or encoding NumPy scalar types and pathlib paths. It passes the official TOML test suite maintained by the toml-lang organization and remains one of the most widely downloaded TOML implementations for Python thanks to its simplicity and long-standing API stability.

What You Get

• loads/load - Parse a TOML string or file into a native Python dictionary.
• dumps/dump - Serialize a Python dictionary back into TOML-formatted text or a file.
• Pluggable encoders/decoders - Swap in TomlPreserveCommentEncoder, TomlArraySeparatorEncoder, TomlNumpyEncoder, or TomlPathlibEncoder for specialized output needs.
• Ordered and inline-table support - Custom _dict classes and an InlineTableDict marker for round-tripping table structure.
• TOML test-suite compliance - Validated against the official toml-lang/toml-test conformance suite.

Common Use Cases

• Application configuration - Developers load config.toml-style files into a Python dict without writing a custom parser.
• Config round-tripping - Tools that read a TOML file, modify a few values, and write it back use the preserve-comment and preserve-inline-dict encoders to avoid clobbering unrelated formatting.
• Data interchange in CLIs - Command-line tools accept or emit TOML as a structured, human-editable alternative to JSON for user-facing config.
• Scientific data export - Projects using NumPy scalar types serialize results to TOML via TomlNumpyEncoder instead of hand-rolling type coercion.

Under The Hood

Architecture

The library is organized as a small, flat package (toml/) with a clear split between decoder.py (parsing TOML text into Python objects via a hand-written recursive-descent style scanner built around regex primitives like TIME_RE) and encoder.py (walking a Python dict/list structure and emitting TOML syntax). tz.py supplies a minimal TomlTz tzinfo implementation for TOML’s offset-datetime type, and ordered.py provides an ordered-dict compatibility shim. The public surface in __init__.py simply re-exports decoder/encoder symbols (load, loads, dump, dumps, and the various TomlEncoder/TomlDecoder subclasses), so there is no internal dependency injection or layering beyond this two-module split - changing the core TomlDecoder/TomlEncoder base classes would ripple through every specialized subclass since they all inherit and override specific methods rather than composing behavior.

Tech Stack

Pure Python with zero required runtime dependencies, supporting an unusually wide interpreter matrix (Python 2.6/2.7 through 3.12, plus PyPy) as declared in setup.py’s python_requires and tox.ini’s envlist. NumPy is an optional integration point only (used by TomlNumpyEncoder to detect np.floatX/np.intX scalar types) and by the test suite, not a hard dependency. Packaging is classic setuptools/distutils via setup.py; there is no pyproject.toml-based build backend. CI runs on GitHub Actions using a custom Docker container (warchantua/py-toml-dev) that layers in Go and the toml-lang/toml-test conformance binary.

Code Quality

Tests live under tests/ (decoding_test.py, encoding_test.py, test_api.py) and are run via pytest through tox, with pytest-cov for coverage and codecov upload wired into a dedicated tox environment. Tests are largely regression-style, each pinned to a specific historical GitHub issue number (e.g. test_bug_430, test_bug_148), rather than being organized around behavior/spec sections. flake8 enforces style (max line length 80) via a dedicated tox check environment. Type stubs (.pyi files) exist alongside every module for static-typing consumers, though the implementation itself is not type-annotated. Error handling is explicit and purposeful: TomlDecodeError computes and reports the line, column, and character offset of a parse failure rather than surfacing a bare exception.

What Makes It Unique

The library’s defining trait is API parity with Python’s built-in json module (load/loads/dump/dumps), which makes it an near drop-in swap for code that already speaks JSON. Its real differentiator is the encoder/decoder plugin system: rather than a single fixed serialization format, callers can select TomlPreserveCommentEncoder/Decoder to avoid destroying comments on a read-modify-write cycle, TomlArraySeparatorEncoder for custom array formatting, or TomlNumpyEncoder/TomlPathlibEncoder for domain-specific type coercion - a level of pluggability most competing TOML parsers do not expose. Conformance against the independent toml-lang/toml-test suite is an explicit, ongoing project goal rather than an informal claim.