API reference

This page is auto-generated from the toons module type stubs.

toons

TOONS Python API for parsing and serializing TOON format.

__version__ = '0.7.0' module-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

ToonDecodeError

Bases: ValueError

Exception raised by the TOON decoder when input cannot be parsed.

Subclasses ValueError for backward compatibility, so existing except ValueError handlers continue to catch parse failures.

Attributes:

Name	Type	Description
line	Optional[int]	1-based line number where the error was detected, or None if the location is unknown (e.g. empty input).
source	Optional[str]	The raw source line (including original indentation) where the error was detected, or None if unknown.

The default message is formatted as "Line N: <detail>" when a line number is available, matching the canonical TypeScript reference implementation (@toon-format/toon).

Example

try: ... toons.loads("items[3]: a,b") ... except toons.ToonDecodeError as exc: ... print(exc.line, exc.source, str(exc))

dump(obj, fp, *, indent=2, delimiter=',', key_folding=None, flatten_depth=None) builtin

Serialize a Python object to a TOON formatted file.

Convert a Python object to TOON format and write it to a file-like object.

Parameters:

Name	Type	Description	Default
obj	Any	A Python object to serialize (dict, list, str, int, float, bool, None)	required
fp	IO[str]	A file-like object with a write() method	required
indent	int	Number of spaces per indentation level (default: 2, minimum: 2)	2

Raises:

Type	Description
ValueError	If indent is less than 2

Example

import toons data = {"name": "Alice", "age": 30} with open('data.toon', 'w') as f: ... toons.dump(data, f)

Custom indentation

with open('data.toon', 'w') as f: ... toons.dump(data, f, indent=4)

dumps(obj, *, indent=2, delimiter=',', key_folding=None, flatten_depth=None) builtin

Serialize a Python object to a TOON formatted string.

Convert a Python object (dict, list, or primitive) to its TOON representation.

Parameters:

Name	Type	Description	Default
obj	Any	A Python object to serialize (dict, list, str, int, float, bool, None)	required
indent	int	Number of spaces per indentation level (default: 2, minimum: 2)	2

Returns:

Type	Description
str	A string containing the TOON representation of the object

Raises:

Type	Description
ValueError	If indent is less than 2

Example

import toons data = {"name": "Alice", "tags": ["admin", "user"]} toon_str = toons.dumps(data) print(toon_str) name: Alice tags[2]: admin,user

Custom indentation

toon_str = toons.dumps(data, indent=4)

load(fp, *, strict=True, expand_paths=None, indent=None) builtin

Deserialize a TOON formatted file to a Python object.

Read TOON data from a file-like object and return the corresponding Python object.

Parameters:

Name	Type	Description	Default
fp	IO[str]	A file-like object with a read() method returning a string	required
strict	bool	If True (default), enforce strict TOON v3.0 compliance. If False, allow some leniency (e.g. blank lines in arrays).	True

Returns:

Type	Description
Any	A Python object (dict, list, or primitive) decoded from the file

Raises:

Type	Description
ToonDecodeError	If the input is malformed. See loads for details.

Example

import toons with open('data.toon', 'r') as f: ... data = toons.load(f)

loads(s, *, strict=True, expand_paths=None, indent=None) builtin

Deserialize a TOON formatted string to a Python object.

Parse a string containing TOON (Token-Oriented Object Notation) data and return the corresponding Python object.

Parameters:

Name	Type	Description	Default
s	str	A string containing TOON formatted data	required
strict	bool	If True (default), enforce strict TOON v3.0 compliance. If False, allow some leniency (e.g. blank lines in arrays).	True

Returns:

Type	Description
Any	A Python object (dict, list, or primitive) decoded from the TOON string

Raises:

Type	Description
ToonDecodeError	If the input is malformed. Subclass of ValueError; carries .line (1-based) and .source (raw line) attributes for programmatic access.

Example

import toons data = toons.loads("name: Alice\nage: 30") print(data)

to_json(s, *, strict=True, expand_paths=None, indent=None) builtin

Convert a TOON formatted string to a JSON formatted string.

Parse a string containing TOON (Token-Oriented Object Notation) data and return the corresponding JSON string using Python's standard library json module.

Parameters:

Name	Type	Description	Default
s	str	A string containing TOON formatted data	required
strict	bool	If True (default), enforce strict TOON v3.0 compliance. If False, allow some leniency (e.g. blank lines in arrays).	True
expand_paths	Optional[str]	Path expansion mode: None, "off", "safe", "always".	None
indent	Optional[int]	Number of spaces per JSON indentation level, or None for compact JSON (default: 2)	None

Returns:

Type	Description
str	A string containing JSON decoded from the TOON string

Raises:

Type	Description
ToonDecodeError	If the input is malformed. See loads for details.

Example

import toons json_str = toons.to_json("name: Alice\nage: 30") print(json_str) { "name": "Alice", "age": 30 }