toon-for-phyton 0.1.0
Toon for Phyton: Python encoder/decoder for the TOON (Token-Oriented Object Notation) format.
Requires Python: >=3.10
Keywords: serialization, toon, json, llm, logging, telemetry

# Toon for Phyton

Python port of [ToonNet](https://github.com/Nicola898989/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:

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

No external dependencies.

## Quick start

```python
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

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

### Key folding and path expansion

```python
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.