toons

library0.7.0pypypi✓ verified 28d ago

toons is a high-performance Python library for parsing and serializing TOON (Token Oriented Object Notation), implemented in Rust for speed. It offers an API that mirrors Python's built-in `json` module, making it easy to convert Python objects to TOON strings and vice-versa. TOON is a token-efficient data serialization format specifically designed to reduce token counts for Large Language Models. The current version is 0.5.4, with frequent minor releases addressing fixes and specification compliance.

serialization llm-agents ai-ml

pip install toons

github ↗package ↗

INSTALL

IMPORT

SIG · TOONS

toons

serializationpythonv0.7.0

Install

1.6s avg

Import

—

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.7.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 19.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

loads

✓ from toons import loads

dumps

✓ from toons import dumps

This quickstart demonstrates how to serialize a Python dictionary and a list of dictionaries (tabular data) into TOON format, and then parse a TOON string back into a Python object using `toons.dumps` and `toons.loads`, mirroring the standard `json` library API.

import toons # Sample Python data data = { "name": "Alice", "age": 30, "tags": ["python", "rust", "toon"] } # Serialize Python data to TOON string toon_string = toons.dumps(data) print("--- TOON String ---") print(toon_string) # Expected output (simplified, actual format may vary slightly based on spec): # name: Alice # age: 30 # tags[3]: python,rust,toon # Parse TOON string back to Python data parsed_data = toons.loads(toon_string) print("\n--- Parsed Python Data ---") print(parsed_data) # Expected output: # {'name': 'Alice', 'age': 30, 'tags': ['python', 'rust', 'toon']} # Example with tabular data (common for LLMs) users = [ {"id": 1, "name": "Bob", "active": True}, {"id": 2, "name": "Charlie", "active": False} ] tabular_toon = toons.dumps(users) print("\n--- Tabular TOON String ---") print(tabular_toon) # Expected output (simplified): # [2]{id,name,active}: # 1,Bob,true # 2,Charlie,false

Debug

Known issues

breakingVersion 0.5.0 introduced compliance with TOON Specification v3.0, potentially causing breaking changes for users relying on data formatted under older TOON specifications (e.g., v2.0 from versions 0.3.x). Ensure your TOON data adheres to v3.0 when upgrading.

fix

Review the TOON Specification v3.0 for any changes relevant to your data structures and update your TOON inputs/outputs accordingly.

affects: >=0.5.0

gotchaOlder versions (prior to 0.5.3) had issues with deserialization of special unicode characters and (prior to 0.5.2) with serialization of datetime objects. If you're handling complex strings or datetimes, ensure you are on a recent version.

fix

Upgrade to `toons` version 0.5.3 or later to ensure correct handling of unicode and datetime types.

affects: <0.5.3

gotchaBy default, `toons` enforces strict compliance with the TOON v3.0 specification. Malformed TOON strings (e.g., those with incorrect indentation, invalid escape sequences, or blank lines in arrays) will raise errors during parsing. For lenient parsing, strict mode can be explicitly disabled.

fix

Ensure your TOON input strictly adheres to the v3.0 specification, or pass `strict=False` to `toons.loads()` for more tolerant parsing, e.g., `toons.loads(toon_str, options={'strict': False})`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'toons.json'

The `toons` library provides its `dumps` and `loads` functions directly under the main `toons` module, not within a nested `toons.json` submodule.

fix

Import the `toons` module directly: `import toons` then use `toons.dumps()` or `toons.loads()`.

TypeError: Object of type <YourClassName> is not TOON serializable

The `toons.dumps` function encountered a Python object type (e.g., a custom class instance, set, or datetime object) that it does not inherently know how to convert into a TOON primitive.

fix

Convert the object to a TOON-serializable type before dumping, or provide a `default` function to `toons.dumps` to handle custom types: `toons.dumps(data, default=my_serializer_function)`.

toons.TOONDecodeError: Invalid TOON string

The input string provided to `toons.loads` is not a syntactically valid TOON document or contains malformed data.

fix

Verify the input string for malformation and ensure it strictly adheres to the TOON specification before passing it to `toons.loads`.

ERROR: Failed building wheel for toons

The `toons` library, being implemented in Rust, requires the Rust toolchain and potentially system build tools to compile its Python extension during installation, which were not found or configured on your system.

fix

Install the Rust toolchain (`rustup install stable`, `rustup update`) and any necessary system build tools (e.g., `build-essential` on Linux, Xcode Command Line Tools on macOS, Visual Studio Build Tools on Windows), then retry `pip install toons`.

Upgrade

Version history

0.7.0latest on PyPI · released May 21, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

38 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/alesanfra/toons ↗

packagehttps://pypi.org/project/toons/ ↗