TOON for Python

The official Python implementation of TOON (Token-Oriented Object Notation): a compact, human-readable encoding of the JSON data model, designed to save tokens in LLM prompts.

• Complete: implements TOON specification 4.1 and passes every official conformance fixture.
• Familiar: dumps, dump, loads, and load, like the json module.
• Pure Python, no dependencies, fully typed, Python 3.10+.

import toon

data = {
    "context": {"task": "Our favorite hikes together", "location": "Boulder"},
    "friends": ["ana", "luis", "sam"],
    "hikes": [
        {"id": 1, "name": "Blue Lake Trail", "distanceKm": 7.5, "wasSunny": True},
        {"id": 2, "name": "Ridge Overlook", "distanceKm": 9.2, "wasSunny": False},
    ],
}

print(toon.dumps(data))

context:
  task: Our favorite hikes together
  location: Boulder
friends[3]: ana,luis,sam
hikes[2]{id,name,distanceKm,wasSunny}:
  1,Blue Lake Trail,7.5,true
  2,Ridge Overlook,9.2,false

assert toon.loads(toon.dumps(data)) == data

Installation

pip install toon-python
# or
uv add toon-python

The distribution is named toon-python; the module is toon. Optional extras: toon-python[pydantic] for the Pydantic integration and toon-python[tokens] for toon --stats. Up to 0.9 the distribution was toon-format, which still works and installs toon-python.

Usage

toon.dumps(obj, *, indent_size=2, delimiter=",", default=None, sort_keys=False)
toon.loads(s, *, strict=True, indent_size=2, parse_float=None, parse_int=None,
           object_hook=None, object_pairs_hook=None)

dump and load do the same with files. Invalid documents raise toon.ToonDecodeError, a ValueError that carries the line and source of the error. The package also provides a toon command and a Pydantic integration:

toon data.json -o data.toon   # JSON to TOON
toon --check response.toon    # validate only

Documentation

The full documentation is at toon-python.readthedocs.io: usage, the Python type mapping, the choices the specification leaves to implementations, the command line, Pydantic, and the API reference.

Migrating from toon_format 0.9

pip install toon-format and import toon_format still work: the toon-format distribution now installs toon-python, and toon_format delegates to the new API with a DeprecationWarning. See the migration guide.

Contributing

See CONTRIBUTING.md. Project conventions for humans and coding agents are in AGENTS.md.

Authors

The people who wrote this package are listed in AUTHORS; every contributor is on the contributors page.

License

MIT