toon-convertor 1.0.0

TOON – Token Optimised Object Notation. A compact, human-readable alternative to JSON.

🎯 TOON — Token Optimised Object Notation

TOON is a compact, human-readable data format designed as a token-efficient alternative to JSON.
It is object-oriented, whitespace-aware, and fully round-trips with JSON.

---

Why TOON?

Feature	JSON	TOON
Key quotes required	✅ Yes	❌ No
Brace/comma noise	✅ High	❌ Minimal
Comments	❌ No	✅ Yes (#)
Typed objects	❌ No	✅ @TypeName
Multiline strings	❌ Awkward	✅ `
Token count	Higher	~15–30% fewer
Round-trip with JSON	—	✅ Lossless

Token comparison

{"name": "Alice", "age": 30, "active": true, "city": "Berlin"}

vs

name: Alice
age: 30
active: true
city: Berlin

TOON is especially useful in LLM prompts, config files, and API responses where token count matters.

---

Installation

pip install toon-convertor

---

Quick Start

import toon

# --- Serialize Python → TOON ---
data = {
    "name": "Alice",
    "age": 30,
    "active": True,
    "skills": ["Python", "LangChain", "RAG"],
    "address": {"city": "Berlin", "country": "Germany"},
}

toon_str = toon.dumps(data)
print(toon_str)

Output:

name: Alice
age: 30
active: true
skills: [Python, LangChain, RAG]
address:
  city: Berlin
  country: Germany

# --- Deserialize TOON → Python ---
obj = toon.loads(toon_str)
print(obj["name"])    # Alice
print(obj["age"])     # 25
print(obj["active"])  # True

# --- JSON ↔ TOON conversion ---
import json

json_str  = json.dumps(data)
toon_str  = toon.from_json(json_str)   # JSON → TOON
back_json = toon.to_json(toon_str)     # TOON → JSON

---

TOON Format Specification

Key-Value Pairs

name: Alice
age: 30
score: 98.6
active: true
nothing: null

Strings (quotes only when needed)

city: Berlin
full_name: "Alice Smith"
bio: "Software Engineer"

Nested Objects

# Indented block
address:
  city: Berlin
  pin: 10115

# Inline object
point: {x: 10, y: 20}

Arrays

# Inline (simple values)
tags: [python, llm, rag]
scores: [98, 87, 76]

# Multi-line
skills:
  - Python
  - LangChain
  - FastAPI

Typed Objects (OO feature)

@Person
  name: Alice
  age: 30
  role: "Engineer"

Parsed as:

{"__type__": "Person", "name": "Alice", "age": 30, "role": "Engineer"}

Comments

# Full-line comment
name: Alice  # inline comment

Multiline Strings

bio: |
  Software Engineer based in Berlin.
  Loves open source and clean code.
  Building great tools daily.

Type Inference

TOON value	Python type
42	int
3.14	float
true / false	bool
null / none / ~	None
"hello"	str
hello (bare)	str

---

API Reference

toon.loads(s)

Parse a TOON string → Python object.

toon.load(fp)

Parse TOON from a file-like object.

toon.dumps(obj, *, indent=2)

Serialize Python object → TOON string.

toon.dump(obj, fp, *, indent=2)

Serialize Python object → write to file.

toon.from_json(json_str, *, indent=2)

Convert JSON string → TOON string.

toon.to_json(toon_str, *, indent=None, sort_keys=False)

Convert TOON string → JSON string.

---

CLI

TOON ships with a command-line tool:

# Convert TOON → JSON
toon to-json data.toon
toon to-json data.toon --indent 4
toon to-json data.toon --compact

# Convert JSON → TOON
toon from-json data.json

# Pipe support
cat data.json | toon from-json
cat data.toon | toon to-json

# Validate TOON
toon validate data.toon

---

Use Cases

• LLM prompts — fewer tokens, same information
• Config files — more readable than JSON, less strict than YAML
• API responses — compact alternative where bandwidth matters
• Data interchange — anywhere JSON is used but verbosity is a cost

---

Contributing

1. Fork the repo
2. pip install -e ".[dev]"
3. Run tests: pytest
4. Submit a PR!

---

License

MIT © toon contributors