Quick Start

This guide covers the essential features of TOON Converter in 5 minutes.

Simple Facade API

The facade API (import toonverter as toon) provides simple functions for 90% of use cases.

Encoding and Decoding

import toonverter as toon

# Encode Python dict to TOON
data = {"name": "Alice", "age": 30, "city": "NYC"}
toon_str = toon.encode(data)
print(toon_str)
# Output:
# name: Alice
# age: 30
# city: NYC

# Decode TOON back to Python
decoded = toon.decode(toon_str)
print(decoded)
# Output: {'name': 'Alice', 'age': 30, 'city': 'NYC'}

Working with Files

import toonverter as toon

# Load data from any format
data = toon.load('data.json', format='json')

# Save as TOON
toon.save(data, 'data.toon', format='toon')

# Convert between formats directly
toon.convert(
    source='data.json',
    target='data.toon',
    from_format='json',
    to_format='toon'
)

Token Analysis

import toonverter as toon

data = {"name": "Alice", "age": 30, "city": "NYC"}

# Analyze token usage across formats
report = toon.analyze(data, compare_formats=['json', 'toon'])

print(f"Best format: {report.best_format}")
print(f"Token savings: {report.max_savings_percentage:.1f}%")
# Output:
# Best format: toon
# Token savings: 33.3%

Listing Formats

import toonverter as toon

# Check available formats
print(toon.list_formats())
# Output: ['csv', 'json', 'toml', 'toon', 'xml', 'yaml']

Object-Oriented API

For more control, use the object-oriented API with configurable options.

Custom Encoder

from toonverter import Encoder

encoder = Encoder(
    format='toon',
    delimiter=',',
    compact=True,
    sort_keys=True
)

data = {"name": "Alice", "age": 30}
encoded = encoder.encode(data)

Custom Decoder

from toonverter import Decoder

decoder = Decoder(
    format='toon',
    strict=True,  # Enable strict validation
    infer_types=True
)

toon_str = "name: Alice\\nage: 30"
decoded = decoder.decode(toon_str)

Stateful Converter

from toonverter import Converter

# Create converter with default options
converter = Converter(
    from_format='json',
    to_format='toon',
    compact=True
)

# Convert multiple files with same settings
converter.convert_file('data1.json', 'data1.toon')
converter.convert_file('data2.json', 'data2.toon')

Token Analyzer

from toonverter import Analyzer

analyzer = Analyzer(model='gpt-4')  # Specify tokenizer model

data = {"users": [...]}  # Your data

# Analyze multiple formats
report = analyzer.analyze_multi_format(
    data,
    formats=['json', 'yaml', 'toon']
)

print(f"JSON tokens: {report.format_results['json'].token_count}")
print(f"TOON tokens: {report.format_results['toon'].token_count}")
print(f"Savings: {report.max_savings_percentage:.1f}%")

Working with Different Data Types

Nested Objects

import toonverter as toon

data = {
    "user": {
        "name": "Alice",
        "address": {
            "city": "NYC",
            "zip": "10001"
        }
    }
}

toon_str = toon.encode(data)
# Output:
# user:
#   name: Alice
#   address:
    city: NYC
#     zip: "10001"

Arrays

import toonverter as toon

# Simple array
data = {"tags": ["python", "llm", "optimization"]}
toon_str = toon.encode(data)
# Output: tags[3]: python,llm,optimization

# Array of objects (tabular form)
data = {
    "users": [
        {"name": "Alice", "age": 30},
        {"name": "Bob", "age": 25}
    ]
}
toon_str = toon.encode(data)
# Output:
# users[2]{name,age}:
#   Alice,30
#   Bob,25

Type Preservation

import toonverter as toon
from datetime import datetime

data = {
    "count": 100,
    "price": 19.99,
    "active": True,
    "updated": datetime(2025, 1, 15, 10, 30, 0)
}

toon_str = toon.encode(data)
# Types are preserved in TOON format

decoded = toon.decode(toon_str)
assert isinstance(decoded['count'], int)
assert isinstance(decoded['price'], float)
assert isinstance(decoded['active'], bool)

Command-Line Interface

Install CLI support:

pip install toonverter[cli]

Basic Commands

# Convert files
toonverter convert data.json data.toon --from json --to toon

# Encode to TOON
toonverter encode data.json --output data.toon

# Decode from TOON
toonverter decode data.toon --output data.json --format json

# Analyze token usage
toonverter analyze data.json --compare json toon yaml

# List supported formats
toonverter formats

Integration Examples

Pandas DataFrame

import pandas as pd
from toonverter.integrations import pandas_to_toon, toon_to_pandas

df = pd.DataFrame({
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [30, 25, 35]
})

# Convert to TOON (uses optimal tabular format)
toon_str = pandas_to_toon(df)

# Convert back
restored_df = toon_to_pandas(toon_str)

Pydantic Models

from pydantic import BaseModel
from toonverter.integrations import pydantic_to_toon, toon_to_pydantic

class User(BaseModel):
    name: str
    age: int

user = User(name="Alice", age=30)

# Serialize to TOON
toon_str = pydantic_to_toon(user)

# Deserialize from TOON
restored = toon_to_pydantic(toon_str, User)

LangChain Documents

from langchain.schema import Document
from toonverter.integrations import langchain_to_toon, toon_to_langchain

doc = Document(
    page_content="Important information",
    metadata={"source": "doc.pdf"}
)

# Convert for efficient storage
toon_str = langchain_to_toon(doc)

# Restore
restored_doc = toon_to_langchain(toon_str)

FastAPI Responses

from fastapi import FastAPI
from toonverter.integrations import TOONResponse

app = FastAPI()

@app.get("/users", response_class=TOONResponse)
async def get_users():
    return {"users": [...], "count": 100}
    # Automatically serialized as TOON

Best Practices

  1. Use Tabular Format for Uniform Data

    # This will automatically use tabular format (most efficient)
data = {
    "items": [
        {"id": 1, "name": "Item1"},
        {"id": 2, "name": "Item2"}
    ]
}

  2. Enable Strict Mode for Production

    from toonverter import Decoder

decoder = Decoder(strict=True)  # Catch validation errors

  3. Analyze Before Deploying

    import toonverter as toon

# Test with real data
report = toon.analyze(your_data, compare_formats=['json', 'toon'])
if report.max_savings_percentage > 30:
    print("TOON is worth it!")

  4. Use Type Hints

    from typing import Any
import toonverter as toon

def process_data(data: dict[str, Any]) -> str:
    return toon.encode(data)

Next Steps