toon-for-phyton 0.1.0

Toon for Phyton: Python encoder/decoder for the TOON (Token-Oriented Object Notation) format.

Toon for Phyton

Python port of ToonNet: a dependency-free encoder/decoder for TOON (Token-Oriented Object Notation), aimed at reducing JSON verbosity while keeping deterministic structure for logs and LLM prompts.

Why TOON

• Indentation-driven structure instead of {} and [].
• Tabular arrays declare schema and delimiter once (users[2]{id,name}).
• Optional length markers ([#N]) make streamed data predictable.
• Key folding (dotted paths) plus path expansion to cut repeated keys.

Installation

Install from PyPI (recommended) or work editable:

pip install toon-for-phyton
# or for local dev
pip install -e .

No external dependencies.

Quick start

from toonforphyton import (
    encode,
    decode,
    ToonOptions,
    ToonDecodeOptions,
    ToonDelimiter,
    KeyFoldingMode,
    PathExpansionMode,
)

payload = {
    "users": [
        {"id": 1, "name": "Alice", "role": "admin"},
        {"id": 2, "name": "Bob", "role": "user"},
    ]
}

options = ToonOptions(delimiter=ToonDelimiter.COMMA, use_length_marker=False)
text = encode(payload, options)
print(text)
# users[2]{id,name,role}:
#  1,Alice,admin
#  2,Bob,user

data = decode(text, ToonDecodeOptions())
print(data["users"][0]["name"])  # Alice

Inline primitive arrays

encode({"tags": ["prod", "api", "v1"]})
# tags[3]: prod,api,v1

Key folding and path expansion

folded = encode({"api": {"v1": {"status": "ok"}}},
                ToonOptions(key_folding=KeyFoldingMode.SAFE))

decoded = decode(folded)  # dotted keys preserved
expanded = decode(folded, ToonDecodeOptions(expand_paths=PathExpansionMode.SAFE))

Core API

• encode(value, options=None) -> str: serializes dicts, lists, dataclasses, namedtuples, and objects with __dict__.
• decode(text, options=None) -> Any: returns native Python structures (dict/list/str/int/bool/Decimal/None).

Encoding options (ToonOptions)

• indent: spaces per level (default 1).
• delimiter: ToonDelimiter.COMMA | TAB | PIPE.
• use_length_marker: emit [#N] for counts.
• key_folding: KeyFoldingMode.OFF | SAFE.
• flatten_depth: max segments for folding (default unlimited).
• new_line: newline sequence (default \n).
• default_converter: optional callable for custom types.

Decoding options (ToonDecodeOptions)

• indent: expected spaces per level (default 1).
• strict: validate declared counts (default True).
• expand_paths: PathExpansionMode.OFF | SAFE.
• length_mismatch_behavior: SILENT | WARN | ERROR.
• warning_sink: optional list receiving ToonDecodeWarning when WARN.

Compatibility and notes

• No external dependencies; works on Python 3.10+.
• Numbers stay as int or Decimal when possible; NaN/Infinity encode as null.
• For custom types use default_converter or expose a clean __dict__/dataclass.

Project layout

Toon for Phyton/
├── README.md
├── src/
│   └── toonforphyton/
│       ├── __init__.py
│       ├── constants.py
│       ├── decoder.py
│       ├── encoder.py
│       ├── options.py
│       └── string_utils.py

Suggested roadmap

• Publish to PyPI with metadata and tests.
• Optional reconstruction of dataclasses on decode.
• CLI for quick JSON ↔︎ TOON conversion.