toons 0.7.0

A high-performance TOON (Token Oriented Object Notation) parser and serializer for Python, implemented in Rust.

TOONS - Token Oriented Object Notation Serializer

A high-performance TOON (Token Oriented Object Notation) parser and serializer for Python.

TOONS - Token Oriented Object Notation Serializer - is a fast Rust-based library that provides a Python interface mirroring the json module API, making it easy to work with the TOON format—a token-efficient data serialization format designed specifically for Large Language Models.

TOONS is officially listed among the community implementations of the TOON format.

Documentation

📖 Read the full documentation at toons.readthedocs.io.

Quick start pages:

• 🚀 Getting Started - Installation and first steps
• 💡 Examples - Practical usage examples
• 📚 API Reference - Complete API documentation

Why TOON?

The TOON format achieves 30-60% fewer tokens than equivalent JSON, making it ideal for LLM contexts where token count impacts costs and context capacity.

In this simple example we can achive -40% with respect to JSON:

JSON (26 tokens):

{"users": [{"name": "Alice", "age": 25}, {"name": "Bob", "age": 30}]}

TOON (16 tokens):

users[2]{name,age}:
  Alice,25
  Bob,30

Note: Calculations were done using Anthropic Claude tokenizer, you can experiment with different tokenizer here

Features

• 🚀 Fast: Rust implementation with PyO3 bindings
• 📊 Token-Efficient: 30-60% fewer tokens than JSON
• 🔄 Familiar API: Drop-in replacement for json module
• ✅ Spec Compliant: Full TOON Specification v3.0 support
• 🐍 Python Native: Works with standard Python types

Quick Start

Installation

pip install toons

Basic Usage

import toons

# Parse TOON string
data = toons.loads("""
name: Alice
age: 30
tags[3]: python,rust,toon
""")
print(data)
# {'name': 'Alice', 'age': 30, 'tags': ['python', 'rust', 'toon']}

# Serialize to TOON
user = {"name": "Bob", "age": 25, "active": True}
print(toons.dumps(user))
# name: Bob
# age: 25
# active: true

# Convert TOON to JSON
print(toons.to_json("name: Alice\nage: 30", indent=2))
# {
#   "name": "Alice",
#   "age": 30
# }

File Operations

import toons

# Write to file
with open("data.toon", "w") as f:
    toons.dump({"message": "Hello, TOON!"}, f)

# Read from file
with open("data.toon", "r") as f:
    data = toons.load(f)

Development

# Clone repository
git clone https://github.com/alesanfra/toons.git
cd toons

# Create venv and install dependencies
uv venv -p 3.14
uv sync --frozen

# Build module
uv run maturin develop --uv

# Run tests
uv run pytest

See the Development Guide for more details.

Targets

Starting with v0.7.0, to optimize GitHub Actions free-tier credits, we no longer build binary wheels for these targets:

• Linux x86, s390x, and ppc64le, since we had 0 downloads during the period from 2026-04-20 to 2026-05-20
• Linux armv7l, since we had only 6 downloads during the period from 2026-04-20 to 2026-05-20
• Windows x86 (32-bit), since we had 0 downloads during the period from 2026-04-20 to 2026-05-20

Source distributions will remain available, so you will still be able to install toons if you also have the Rust compiler installed.

Contributing

Contributions are welcome! Please follow Conventional Commits and run tests before submitting.

See Contributing Guide for details.

License

This project is licensed under the Apache License 2.0. See LICENSE file for details.