TOON Format for Python: Complete Developer Guide

Python has become the language of choice for AI/ML development, data science, and LLM integration. Whether you're building machine learning pipelines, working with LLMs through Claude or OpenAI APIs, or handling large datasets, you're likely dealing with JSON serialization inefficiencies.

This comprehensive guide shows Python developers exactly how to implement the TOON format (Token-Oriented Object Notation) to achieve 30-60% token reduction compared to JSON. You'll learn practical patterns for converting JSON to TOON, integrating with FastAPI/Flask, and optimizing your LLM API costs while maintaining data integrity.

What is TOON and Why Python Developers Need It

The Problem: JSON Waste in LLM Applications

Every time you call GPT-4, Claude, or Gemini, you pay per token. Consider this customer database query in JSON:

{
  "customers": [
    { "id": 1, "name": "Alice Johnson", "email": "alice@example.com", "status": "active", "tier": "premium" },
    { "id": 2, "name": "Bob Smith", "email": "bob@example.com", "status": "active", "tier": "basic" },
    { "id": 3, "name": "Charlie Brown", "email": "charlie@example.com", "status": "inactive", "tier": "free" }
  ]
}

This JSON uses 189 tokens to represent just 3 customer records.

The Solution: TOON Format for Python

The exact same data in TOON format:

customers[3]{id,name,email,status,tier}:
  1,Alice Johnson,alice@example.com,active,premium
  2,Bob Smith,bob@example.com,active,basic
  3,Charlie Brown,charlie@example.com,inactive,free

This TOON uses only 73 tokens — a 61.4% reduction.

Why Python Developers Should Adopt TOON

• Direct LLM Integration - Works with LangChain, LlamaIndex, Claude SDK
• ML Pipeline Optimization - Perfect for feature stores and embeddings
• Cost Control - Transparent, measurable savings on API bills
• Accuracy Improvement - Explicit structure helps LLMs parse data correctly
• Production-Ready - Official Python library with full feature support
• Ecosystem Integration - Works seamlessly with FastAPI, Flask, Pydantic

Installation & Setup: Getting TOON into Your Python Project

Step 1: Install the TOON Package

The official TOON Python library is published on PyPI as toon-format.

Using pip (recommended):

pip install toon-format

Using Poetry:

poetry add toon-format

Using pipenv:

pipenv install toon-format

Install from GitHub (for latest features):

pip install git+https://github.com/toon-format/toon-python.git

Step 2: Verify Installation

Create a test file (test_toon.py):

from toon_format import encode, decode

# Test basic encoding
data = {
    "users": [
        {"id": 1, "name": "Alice", "role": "admin"},
        {"id": 2, "name": "Bob", "role": "user"}
    ]
}

# Encode to TOON
toon_string = encode(data)
print("TOON Format:")
print(toon_string)

# Decode back to Python dict
decoded = decode(toon_string)
print("\nDecoded back to Python:")
print(decoded)

# Verify round-trip
print("\nRound-trip successful:", data == decoded)

Run the test:

python test_toon.py

Step 3: Check Your Python Version

TOON for Python requires Python 3.8+. Verify your version:

python --version

Core Implementation Patterns for Python

Pattern 1: Basic JSON to TOON Conversion

The simplest use case: converting Python dictionaries to TOON format.

from toon_format import encode, decode
import json

# Example: Product catalog
products = {
    "items": [
        {"sku": "PROD001", "name": "Laptop", "price": 999.99, "stock": 45},
        {"sku": "PROD002", "name": "Mouse", "price": 29.99, "stock": 150},
        {"sku": "PROD003", "name": "Keyboard", "price": 79.99, "stock": 87}
    ]
}

# Convert to TOON
toon_data = encode(products)
print("TOON Output:")
print(toon_data)

# Show token savings
json_size = len(json.dumps(products))
toon_size = len(toon_data)
savings = ((json_size - toon_size) / json_size) * 100

print(f"\nJSON size: {json_size} bytes")
print(f"TOON size: {toon_size} bytes")
print(f"Savings: {savings:.1f}%")

Pattern 2: Working with Nested Data

TOON automatically handles nested structures, encoding tabular arrays and preserving nested objects:

from toon_format import encode

# Complex nested structure
company_data = {
    "company": {
        "name": "TechCorp",
        "employees": [
            {"id": 1, "name": "Alice", "department": "Engineering", "salary": 95000},
            {"id": 2, "name": "Bob", "department": "Sales", "salary": 75000},
            {"id": 3, "name": "Charlie", "department": "Marketing", "salary": 65000}
        ]
    }
}

# TOON automatically detects the uniform array
toon_output = encode(company_data)
print(toon_output)

Pattern 3: Custom Delimiters for Maximum Efficiency

Control delimiters to further optimize token usage:

from toon_format import encode

analytics = {
    "metrics": [
        {"date": "2025-01-01", "views": 5420, "clicks": 234, "conversions": 18},
        {"date": "2025-01-02", "views": 6150, "clicks": 289, "conversions": 22},
        {"date": "2025-01-03", "views": 5890, "clicks": 267, "conversions": 20}
    ]
}

# Default comma delimiter
comma_toon = encode(analytics)
print("Comma-delimited:")
print(comma_toon)

# Tab delimiter (more efficient for LLMs)
tab_toon = encode(analytics, delimiter='\t')
print("\nTab-delimited (more efficient):")
print(tab_toon)

Integrating TOON with FastAPI

FastAPI is the modern Python framework for building high-performance APIs. Here's how to integrate TOON:

Use Case 1: TOON Response Format

Allow clients to request responses in TOON format:

from fastapi import FastAPI, Query
from toon_format import encode
from typing import Optional

app = FastAPI(title="TOON-Optimized API")

# Sample database
users_db = [
    {"id": 1, "name": "Alice", "email": "alice@example.com", "active": True},
    {"id": 2, "name": "Bob", "email": "bob@example.com", "active": True},
    {"id": 3, "name": "Charlie", "email": "charlie@example.com", "active": False}
]

@app.get("/users")
def get_users(format: Optional[str] = Query(None, description="Response format: 'json' or 'toon'")):
    """Get all users. Supports both JSON and TOON formats."""
    data = {"users": users_db}
    
    if format == "toon":
        # Return TOON-formatted response
        toon_data = encode(data, delimiter='\t', indent=1)
        return {"format": "toon", "data": toon_data}
    
    # Default: return JSON
    return data

Use Case 2: LLM-Optimized Endpoints

Create endpoints specifically for LLM integration with automatic TOON encoding:

from fastapi import FastAPI
from fastapi.responses import PlainTextResponse
from toon_format import encode
import anthropic

app = FastAPI()

# Sample customer data
customers = [
    {"id": 1, "name": "Alice Corp", "revenue": 250000, "industry": "Technology"},
    {"id": 2, "name": "Bob Services", "revenue": 500000, "industry": "Finance"},
    {"id": 3, "name": "Charlie Inc", "revenue": 120000, "industry": "Retail"}
]

@app.post("/llm/analyze-customers")
async def analyze_customers_with_llm(query: str) -> PlainTextResponse:
    """Analyze customer data using Claude AI with TOON format for efficiency."""
    
    # Prepare data in TOON format
    customer_data = encode(
        {"customers": customers},
        delimiter='\t',
        indent=1
    )
    
    # Create Claude client
    client = anthropic.Anthropic()
    
    # Send to Claude with TOON-formatted data
    message = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1024,
        system=f"You are a business analyst. Analyze the following customer data in TOON format:\n\n{customer_data}",
        messages=[{"role": "user", "content": query}]
    )
    
    return PlainTextResponse(message.content[0].text)

Integrating TOON with Flask

For Flask developers, integrating TOON is equally straightforward:

from flask import Flask, request, jsonify
from toon_format import encode, decode
import json

app = Flask(__name__)

# Check if client prefers TOON format
@app.before_request
def check_toon_format():
    request.prefer_toon = request.headers.get("Accept-Format") == "toon"

@app.after_request
def convert_to_toon_if_requested(response):
    """Convert JSON responses to TOON if requested."""
    if hasattr(request, 'prefer_toon') and request.prefer_toon:
        if response.content_type == "application/json":
            data = json.loads(response.get_data(as_text=True))
            toon_data = encode(data, indent=1)
            response.set_data(toon_data)
            response.content_type = "text/plain; charset=utf-8"
    return response

# Example endpoint
@app.route("/api/customers", methods=["GET"])
def get_customers():
    customers = [
        {"id": 1, "name": "Alice", "email": "alice@example.com", "status": "active"},
        {"id": 2, "name": "Bob", "email": "bob@example.com", "status": "active"},
        {"id": 3, "name": "Charlie", "email": "charlie@example.com", "status": "inactive"}
    ]
    return jsonify({"customers": customers})

if __name__ == "__main__":
    app.run(debug=True)

Usage:

# Get JSON
curl http://localhost:5000/api/customers

# Get TOON
curl -H "Accept-Format: toon" http://localhost:5000/api/customers

Command-Line Usage: TOON CLI

The TOON package includes a CLI tool for converting files:

File Conversion

# Convert JSON to TOON
toon input.json -o output.toon

# Convert TOON to JSON
toon data.toon -o output.json

# Convert from stdin
cat customers.json | toon > customers.toon

# Pretty-print output
toon data.json --pretty

Advanced CLI Options

# Use tab delimiter
toon input.json -o output.toon --delimiter "\t"

# Show token count statistics
toon input.json --stats

# Verbose output
toon input.json -v

Performance Benchmarks

Token Efficiency by Data Type

LLM Performance Comparison

Frequently Asked Questions

Q1: When should I use TOON vs JSON in Python?

Use TOON when:

• Sending data to LLMs (Claude, GPT-4, Gemini)
• Working with uniform tabular data (100+ similar records)
• Token efficiency is critical (API cost concerns)
• Data is being sent to external AI services

Use JSON when:

• Building REST APIs (client compatibility)
• Working with web browsers/frontend
• Deep nesting is common
• Objects have varying fields

Q2: Does TOON work with Pydantic models?

Yes! Convert Pydantic models to TOON easily:

from pydantic import BaseModel
from toon_format import encode

class User(BaseModel):
    id: int
    name: str
    email: str

users = [
    User(id=1, name="Alice", email="alice@example.com"),
    User(id=2, name="Bob", email="bob@example.com")
]

# Convert to list of dicts
users_dict = [u.model_dump() for u in users]

# Encode to TOON
toon_data = encode({"users": users_dict})
print(toon_data)

Q3: What's the performance overhead of TOON encoding?

Minimal:

• Encoding time: ~120µs
• Decoding time: ~150µs
• Token savings: 30-60% (major impact)

The encoding overhead is negligible compared to token cost savings.

Q4: How do I migrate existing code from JSON to TOON?

Gradual migration approach:

# Step 1: Add TOON alongside JSON
import json
from toon_format import encode, decode

# Step 2: Wrap with abstraction
def serialize_data(data, format="json"):
    if format == "toon":
        return encode(data)
    return json.dumps(data)

# Step 3: Gradually switch endpoints to TOON
# /api/v1/users -> JSON (keep for compatibility)
# /api/v2/users -> TOON (new LLM-optimized endpoint)

Conclusion: TOON for Production Python Applications

By integrating TOON into your Python applications, you gain:

• 30-60% LLM token cost reduction — Direct savings on API bills
• Better LLM accuracy (73.9% vs 69.7%) — More reliable results
• Seamless integration — Works with FastAPI, Flask, Pydantic
• Production-ready — Official library with comprehensive testing
• Flexibility — Support for custom delimiters and options

Quick Implementation Checklist

1. Install: pip install toon-format
2. Test: Create test file and verify encoding/decoding
3. Integrate: Add TOON endpoints to FastAPI/Flask
4. Measure: Compare JSON vs TOON token counts
5. Deploy: Gradually roll out to LLM integration paths
6. Monitor: Track token usage and cost savings

Next Steps

1. Install the library: pip install toon-format
2. Try our free tool: Convert JSON to TOON online
3. Build endpoints: Integrate with your FastAPI/Flask apps
4. Measure impact: Calculate token and cost savings
5. Scale gradually: Start with highest-volume LLM integrations

Related Articles

• How to Convert JSON to TOON: Step-by-Step Tutorial
• TOON vs JSON vs YAML: Complete Comparison Guide
• TOON Format for JavaScript Developers
• What is TOON Format? Complete Guide
• TOON Format: Complete Syntax Guide
• LLM Token Optimization: Reduce AI Costs
• Prompt Engineering for LLMs: Complete Masterclass