python-toon

What it is and what it does

python-toon is a bidirectional encoder/decoder for TOON, a data format that combines YAML-style indentation for nested objects with CSV-like tabular format for uniform arrays. It targets LLM token efficiency by eliminating redundant punctuation (braces, brackets, most quotes) while maintaining semantic clarity. The package provides both a Python API (encode/decode functions) and a command-line tool for converting between JSON and TOON formats.

The format supports nested objects, primitive arrays with length markers, tabular arrays (uniform object collections), and mixed arrays. It implements the official TOON specification with strict validation by default, optional lenient parsing, and configurable delimiters (comma, tab, pipe). Since its first release in October 2025, it has reached version 0.1.3 and supports Python 3.8 through 3.12.

Use it for:

• Prepare structured data for LLM prompts where token count directly affects API cost or response latency.
• Convert existing JSON datasets to TOON format for more efficient LLM ingestion via CLI or programmatic API.
• Encode tabular data (lists of uniform objects) into compact CSV-like TOON format for batch LLM processing.
• Bidirectionally convert between JSON and TOON in data pipelines that feed language models.
• Validate TOON-formatted input with strict mode or parse lenient TOON variants with relaxed validation.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Encodes and decodes TOON (Token-Oriented Object Notation), a compact data format designed to represent structured data in 30-60% fewer tokens than JSON, optimized for transmission to Large Language Models.

Yes, if you are building LLM applications where token efficiency matters and you want a standards-compliant TOON implementation. The package is lightweight (no dependencies), well-documented, and covers both API and CLI use cases. The aging maintenance status (283 days since last commit) is a minor concern for a stable format encoder, but the unarchived repository and recent release history suggest it is not abandoned. No known security vulnerabilities.

Install

python-toon on PyPI

pip install python-toon

uv add python-toon

poetry add python-toon

Installing python-toon

Before you install

Low friction: pure Python wheel with no runtime dependencies. Maintenance status is aging—last commit was 283 days ago—but the repository remains active and unarchived with 340 stars.

License in practice

MIT license (permissive): you can use, modify, and distribute this package freely in commercial and private projects, with minimal restrictions.

Quickstart

pip install python-toon

from toon import encode, decode

data = {"name": "Alice", "age": 30}
toon_str = encode(data)
print(toon_str)  # name: Alice\nage: 30

recovered = decode(toon_str)
print(recovered)  # {'name': 'Alice', 'age': 30}

Verify before relying

• Whether the 30-60% token reduction claim has been independently validated against real LLM tokenizers.
• Performance characteristics (encoding/decoding speed) on large datasets or deeply nested structures.
• Compatibility guarantees with the official TypeScript TOON implementation beyond the stated 100% output compatibility.

Package facts

Evidence: python_toon-0.1.3-py3-none-any.whl

Keywords: data-format, encoding, llm, token-efficient, toon

Tags

More Python Modules packages