TOON API Reference¶
toon
¶
TOON encoder/decoder — zero dependencies, stdlib only, Python 3.10+.
Part of zerodep: https://github.com/Oaklight/zerodep Copyright (c) 2026 Peng Ding. MIT License.
Implements the TOON 4.4 specification. The official conformance fixtures
(564 cases: 160 encode, 404 decode) are vendored in toon/fixtures/spec/
and gated by toon/test_toon_conformance.py.
The encoder and decoder follow the TOON reference implementation,
toon-format/toon-python <https://github.com/toon-format/toon-python>_
(MIT License, commit 91413d14), adapted to this module's single-file,
standard-library-only form and public API.
TOON is a compact, human-readable serialization format designed for LLM contexts, achieving 30-60% token reduction vs JSON. It combines YAML-like indentation with CSV-like tabular arrays.
Example::
encode({"name": "Alice", "age": 30})
# 'name: Alice
age: 30' decode("name: Alice age: 30") # {'name': 'Alice', 'age': 30}
EncodeOptions
¶
Bases: TypedDict
Options for TOON encoding.
Attributes:
| Name | Type | Description |
|---|---|---|
indent |
int
|
Number of spaces per indentation level (default: 2). |
delimiter |
str
|
Delimiter character for arrays (default: ","). |
The pre-4.0 lengthMarker option was removed by the specification;
passing it raises :class:ValueError so callers notice the change.
Source code in toon/toon.py
DecodeOptions
¶
Bases: TypedDict
Options for TOON decoding.
Attributes:
| Name | Type | Description |
|---|---|---|
indent |
int
|
Number of spaces per indentation level (default: 2). |
strict |
bool
|
Enforce every check of specification §14 (default: True). |
Source code in toon/toon.py
ToonDecodeError
¶
Bases: Exception
Error raised when TOON decoding fails.
Unlike :class:json.JSONDecodeError, this is not a :class:ValueError
subclass: except ValueError does not catch decode failures, so catch
ToonDecodeError instead. This is the module's public contract.
Attributes:
| Name | Type | Description |
|---|---|---|
msg |
str
|
The unformatted error message. |
line |
int | None
|
1-based line number of the offending line, or |
source |
str | None
|
The offending line as written, or |
Source code in toon/toon.py
encode(value, options=None)
¶
Serialize a Python value to a TOON document.
Args:
value: The value to encode. Mappings, sequences, strings, numbers,
booleans and ``None`` map onto the JSON data model; dates, UUIDs,
paths, enums and dataclasses are converted following §3.
options: Optional encoding options (``indent``, ``delimiter``).
Unknown keys raise :class:`TypeError` rather than being ignored.
Returns:
The TOON document, without a trailing newline.
Raises:
TypeError: A value or mapping key cannot be encoded, or an unknown
option was supplied.
ValueError: An option is invalid, a string contains an unpaired
surrogate, a mapping has colliding keys, or the value is nested
too deeply or contains a reference cycle.
Examples::
encode({"name": "Alice", "age": 30})
# 'name: Alice
age: 30' encode([1, 2, 3], EncodeOptions(delimiter=" ")) # '[3 ]: 1 2 3'
Source code in toon/toon.py
decode(text, options=None)
¶
Deserialize a TOON document to a Python value.
Args:
text: TOON-formatted string, or UTF-8 encoded bytes.
options: Optional decoding options (``indent``, ``strict``).
Unknown keys raise :class:`TypeError` rather than being ignored.
Returns:
Decoded Python value.
Raises:
ToonDecodeError: If the input is malformed or is not valid UTF-8.
TypeError: If ``text`` is not str/bytes/bytearray, an option is
unknown, or ``indent`` is not an int.
ValueError: If ``indent`` is less than one.
Examples::
decode("name: Alice
age: 30") # {'name': 'Alice', 'age': 30} decode("[3]: 1,2,3") # [1, 2, 3]
Source code in toon/toon.py
is_number_token(token)
¶
quote(value)
¶
encode_string(value, delimiter)
¶
encode_key(key)
¶
format_decimal(value)
¶
Format a finite decimal in the canonical number form of §2.
Magnitudes in [1e-6, 1e21) use plain decimal notation without
trailing zeros. Other magnitudes use JSON exponent notation with a
lowercase e and an explicit exponent sign.
Source code in toon/toon.py
format_float(value)
¶
Format a finite float in the canonical number form of §2.
repr yields the shortest digit string that round-trips, so the output
decodes back to the same float. Integral floats of 2**53 and beyond are
written with their exact digits instead: they decode as int, and the
shortest digits would not equal the float (float(2**60) == 2**60 but
1152921504606847000 != 2**60).