Registry / serialization / toon-format

toon-format

JSON →
library0.1.0pypypi✓ verified 86d ago

TOON (Token-Oriented Object Notation) is a compact, human-readable data format designed for LLM prompts to reduce token usage by 30-60% compared to JSON. It achieves this by eliminating redundant punctuation and using a tabular format for uniform data structures. The Python implementation, currently in beta (v0.9.0-beta.1), provides encoding and decoding functionalities, aiming for full compliance with the TOON specification.

pip install toon-format
INSTALL
IMPORT
SIG · TOON-FORMAT
T
toon-format
serializationpythonv0.1.0
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.1.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
glibc
py 3.10
8/12 runs
8/12 runs
py 3.11
8/12 runs
8/12 runs
py 3.12
8/12 runs
8/12 runs
py 3.13
8/12 runs
8/12 runs
py 3.9
8/12 runs
8/12 runs
Code
Verified usage

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

encode
from toon_format import encode
from toon_format.encoder import encode
The `encode` function is directly available from the top-level `toon_format` package.
decode
from toon_format import decode
from toon_format.decoder import decode
The `decode` function is directly available from the top-level `toon_format` package.
load, dump
from toon_format import load, dump
from toon_format.io import load, dump
File I/O functions are exposed at the top level.

This quickstart demonstrates how to encode Python dictionaries and lists into TOON format and decode TOON strings back into Python objects using `toon_format.encode` and `toon_format.decode` functions.

from toon_format import encode, decode # Encode a simple Python dictionary to TOON data_object = {"name": "Alice", "age": 30} toon_object = encode(data_object) print(f"\nEncoded Object:\n{toon_object}") # Expected output: # name: Alice # age: 30 # Encode a list of uniform dictionaries (tabular array) data_list = [ {"id": 1, "name": "Widget", "price": 9.99}, {"id": 2, "name": "Gadget", "price": 19.99} ] toon_list = encode(data_list) print(f"\nEncoded List:\n{toon_list}") # Expected output: # [2]{id,name,price}: # 1,Widget,9.99 # 2,Gadget,19.99 # Decode TOON back to Python objects toon_string_to_decode = """ items[2]: apple,banana """ decoded_data = decode(toon_string_to_decode) print(f"\nDecoded Data:\n{decoded_data}") # Expected output: {'items': ['apple', 'banana']}
toon-format --version
Debug
Known issues
breakingThe library is currently in beta (v0.9.x), and its API may change significantly before the 1.0.0 stable release.
fix
Review the GitHub repository for the latest API changes before upgrading to new beta versions or the eventual 1.0.0 release. Pin specific beta versions if stability is critical.
affects: 0.9.x-beta
gotchaTOON is primarily optimized for uniform arrays of objects (tabular data) and may not always yield significant token savings or be ideal for deeply nested or highly non-uniform JSON structures.
fix
Evaluate TOON's token efficiency for your specific data structures. For deeply nested or irregular data, standard (compacted) JSON might still be more efficient or appropriate. Use TOON primarily for structured, tabular data fed to LLMs.
affects: All
gotchaThere are multiple Python implementations related to TOON (e.g., `py-toon-format`, `python-toon`, `toons`), leading to a fragmented ecosystem. Ensure you are using the official `toon-format/toon-python` implementation for the most up-to-date and spec-compliant version.
fix
Always install `toon-format` via `pip install toon-format` or directly from the official GitHub repository (`pip install git+https://github.com/toon-format/toon-python.git`) to guarantee you're using the intended library. Verify import paths (`from toon_format import ...`) match the official documentation.
affects: All
gotchaThe `decode` function operates in 'strict' mode by default, which means it will raise errors for any syntax inconsistencies, array length mismatches, or delimiter issues in the TOON string.
fix
If you need to parse potentially malformed or lenient TOON, use `decode(toon_string, options={'strict': False})`. However, be aware that disabling strict mode might lead to unexpected parsing results for invalid TOON.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'toon_format'
You likely installed the package using `pip install toon-format`, but the Python import path uses underscores, not hyphens.
fix
Ensure your import statement is `from toon_format import encode, decode` (using an underscore in `toon_format`) after installing `pip install toon-format`.
SyntaxError: Invalid TOON format: Array length mismatch. Expected 3 items, got 2.
The TOON string you are trying to decode has an array length declared (e.g., `items[3]`) that does not match the actual number of items provided in the data rows.
fix
Correct the TOON string so that the declared array length `[N]` precisely matches the number of data rows, or set `strict=False` during decoding (e.g., `decode(toon_string, options={'strict': False})`) to allow lenient parsing.
ValueError: Invalid TOON format: Indentation error.
TOON strictly enforces 2-space indentation for nested objects, similar to YAML. Inconsistent or incorrect indentation will result in a parsing error.
fix
Review your TOON string to ensure all nested objects use exactly 2 spaces per indentation level and are consistent throughout the document. Avoid using tabs for indentation.
Upgrade
Version history
0.1.0latest on PyPI · released Nov 1, 2025
Audit
Dependencies
tiktokenoptionalRequired for accurate token counting when using OpenAI integration.
Agent activity
31 hits · last 30 days
node
26
OpenAI (training)
1
Resources