toonit 0.1.0

Python implementation of the TOON (Token-Oriented Object Notation) format

PyTOON

PyTOON is a compact, human-friendly serializer for TOON – Token-Oriented Object Notation.
It includes a Python scanner, parser, encoder, decoder, and CLI so you can round-trip Python structures through the TOON format.

Features

• Fast encode/decode with perfect round-tripping
• Top-level key folding (a.b: 1 style) with automatic unfolding on decode
• Columnar encoding for lists of dictionaries
• Friendly CLI: pytoon encode, pytoon decode

---

Installation

Published package:

pip install pytoon

Editable install for development:

pip install -e .

Why TOON?

TOON targets structured data where JSON becomes verbose. Compared to JSON it is:

• Smaller for nested or repetitive payloads (often 40–70% savings)
• Friendly for analytics because columnar expansion is built in
• Easier to read and edit thanks to lightweight syntax

Basic Usage

Encode Python → TOON:

import pytoon

s = pytoon.encode({"a": 1, "b": 2})
print(s)

Decode TOON → Python:

data = pytoon.decode(s)

Round-trip guarantee:

original = {"info": {"name": "Femi", "city": "Lagos"}}
assert pytoon.decode(pytoon.encode(original)) == original

Folding Rules

Nested dictionaries are folded into dotted keys during encoding:

pytoon.encode({"a": {"b": 1, "c": 2}})

produces TOON like:

a.b: 1,
a.c: 2

During decoding those dotted keys are unfolded back to their original hierarchy.

Columnar Encoding

Lists of dictionaries are encoded column-by-column automatically:

rows = [
    {"x": 1, "y": 10},
    {"x": 2, "y": 20},
    {"x": 3, "y": 30},
]

encoded = pytoon.encode(rows)

which yields TOON similar to:

x: [1, 2, 3],
y: [10, 20, 30]

Decoding brings the rows back intact:

assert pytoon.decode(pytoon.encode(rows)) == rows

CLI

pytoon encode input.json > out.toon
pytoon decode out.toon
echo '{"a": 1, "b": 2}' | pytoon encode

Tests

pytest

The suite covers parsing, scanning, folding, columnar transforms, error cases, and round-trip behavior.

Project Layout

pytoon/
  core/       # scanner, parser, AST, writer
  encoding/   # folding + columnar transforms
  decoding/   # normalization + validation
  cli.py      # command-line entry points
  api.py      # public encode/decode API

Example TOON

a.b: 1,
list: [1, 2, 3],
info.name: "Femi",
info.city: "Lagos"

License

MIT License. See LICENSE for details.

Contributing

Issues and pull requests are welcome! Feel free to start a discussion if you have ideas for the TOON format or the Python implementation.