TOON Functions¶

Functions for encoding and decoding the TOON serialisation format.

import ctoon

# String I/O
toon = ctoon.dumps({"name": "Alice", "age": 30})
data = ctoon.loads(toon)

# File I/O
ctoon.dump(data, "out.toon")
data = ctoon.load("out.toon")

Reference¶

loads(s: object, flags: ctoon.ReadFlag = ReadFlag.NOFLAG, indent: int = 2, strict: bool = True) → object¶

Parse a TOON string or bytes object. Returns a Python object.

loads(s, flags=ReadFlag.NOFLAG, indent=2, strict=True) -> object

indent overrides indentSize (spec §12) - the number of spaces that count as one indentation level when decoding (default 2). strict=False decodes in non-strict mode (spec §13 strict: false), equivalent to passing ReadFlag.NON_STRICT.

dumps(obj: object | None, indent: int = 2, delimiter: ctoon.Delimiter = Delimiter.COMMA, flags: ctoon.WriteFlag = WriteFlag.NOFLAG) → object¶

Serialize a Python object to a TOON string.

dumps(obj, indent=2, delimiter=Delimiter.COMMA,
flags=WriteFlag.NOFLAG) -> str

load(fp: object, flags: ctoon.ReadFlag = ReadFlag.NOFLAG, indent: int = 2, strict: bool = True) → object¶

Load TOON from a file path (str) or a file-like object with .read().

load(fp, flags=ReadFlag.NOFLAG, indent=2, strict=True) -> object

strict=False decodes in non-strict mode (spec §13 strict: false).

with open(‘data.toon’) as f:
obj = ctoon.load(f)

obj = ctoon.load(‘data.toon’)

dump(obj: object | None, fp: object, indent: int = 2, delimiter: ctoon.Delimiter = Delimiter.COMMA, flags: ctoon.WriteFlag = WriteFlag.NOFLAG) → None¶

Serialize a Python object to a TOON file path or file-like object.

dump(obj, fp, indent=2, delimiter=Delimiter.COMMA,
flags=WriteFlag.NOFLAG)

with open(‘out.toon’, ‘w’) as f:
ctoon.dump(data, f)

ctoon.dump(data, ‘out.toon’)

Spec version¶

The toon-format/spec release this build targets, read from the C core (and checked against supported_spec.conf in the test-suite).

import ctoon

ctoon.__toon_spec__        # "4.1"          spec version
ctoon.__toon_spec_tag__    # "v4.1.2"       spec git tag
ctoon.__toon_spec_date__   # "2026-07-26"   spec release date

ctoon.__toon_spec__: str¶: The TOON spec version this build targets, e.g. "4.1".

ctoon.__toon_spec_tag__: str¶: The toon-format/spec git tag this build targets, e.g. "v4.1.2".

ctoon.__toon_spec_date__: str¶: The release date of the targeted spec, e.g. "2026-07-26".

Aliases¶

encode and decode are aliases for dumps and loads respectively.

encode(*args, **kwargs)¶

dumps(obj: object | None, indent: int = 2, delimiter: ctoon.Delimiter = Delimiter.COMMA, flags: ctoon.WriteFlag = WriteFlag.NOFLAG) -> object

Serialize a Python object to a TOON string.

dumps(obj, indent=2, delimiter=Delimiter.COMMA,
flags=WriteFlag.NOFLAG) -> str

decode(*args, **kwargs)¶

loads(s: object, flags: ctoon.ReadFlag = ReadFlag.NOFLAG, indent: int = 2, strict: bool = True) -> object

Parse a TOON string or bytes object. Returns a Python object.

loads(s, flags=ReadFlag.NOFLAG, indent=2, strict=True) -> object