toons 0.5.4

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

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

# Install dependencies
pip install -r requirements-dev.txt

# Build extension
maturin develop

# Run tests
pytest

See the Development Guide for more details.

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.