API reference

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

toons

TOONS: parse and serialize the TOON format.

__toon_spec__ = '4.1' 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 'utf-8'. errors defaults to 'strict'.

__version__ = '0.9.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 'utf-8'. errors defaults to 'strict'.

ToonDecodeError

Bases: ValueError

Raised by the decoder when input cannot be parsed.

Subclasses ValueError, so existing except ValueError handlers keep catching parse failures.

Attributes:

Name	Type	Description
line	Optional[int]	1-based line number where the error was detected, or None when the location is unknown (for example, empty input).
source	Optional[str]	Raw source line, including its original indentation, or None when unknown.

The message reads "TOON parse error at line N: <detail>" when a line number is available.

Example

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

dump(obj, fp, *, indent_size=None, delimiter=',', indent=None) builtin

Serialize a Python object as TOON and write it to a file-like object.

Parameters:

Name	Type	Description	Default
obj	Any	Object to serialize. See dumps for supported types.	required
fp	IO[str]	File-like object with a write() method.	required
indent_size	Optional[int]	Spaces per indentation level (default 2, minimum 2).	None
delimiter	str	Document delimiter for arrays and tables: "," (default), "\t", or "|".	','
indent	Optional[int]	Deprecated alias of indent_size.	None

Raises:

Type	Description
TypeError	If the object contains a type that cannot be encoded, or a non-string object key.
ValueError	If an option value is invalid, or the object contains a reference cycle.

Example

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

dumps(obj, *, indent_size=None, delimiter=',', indent=None) builtin

Serialize a Python object to a TOON formatted string.

Parameters:

Name	Type	Description	Default
obj	Any	Object to serialize. dict, list, tuple, str, int, float, bool, None, and date/time/datetime objects are supported.	required
indent_size	Optional[int]	Spaces per indentation level (default 2, minimum 2).	None
delimiter	str	Document delimiter for arrays and tables: "," (default), "\t", or "|".	','
indent	Optional[int]	Deprecated alias of indent_size.	None

Returns:

Type	Description
str	The TOON representation of the object.

Raises:

Type	Description
TypeError	If the object contains a type that cannot be encoded, or a non-string object key.
ValueError	If an option value is invalid, or the object contains a reference cycle.

Example

import toons print(toons.dumps({"name": "Alice", "tags": ["admin"]})) name: Alice tags[1]: admin

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

Deserialize TOON data read from a file-like object.

Parameters:

Name	Type	Description	Default
fp	IO[str]	File-like object with a read() method returning a string.	required
strict	bool	If True (default), enforce strict TOON v4.1 compliance.	True
indent_size	Optional[int]	Expected spaces per indentation level (default 2).	None
indent	Optional[int]	Deprecated alias of indent_size.	None

Returns:

Type	Description
Any	The decoded Python object (dict, list, or primitive).

Raises:

Type	Description
ToonDecodeError	If the input is malformed. See loads.
ValueError	If an option value is invalid.

Example

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

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

Deserialize a TOON formatted string to a Python object.

Parameters:

Name	Type	Description	Default
s	str	String containing TOON data.	required
strict	bool	If True (default), enforce strict TOON v4.1 compliance. If False, allow the documented leniencies, such as blank lines inside arrays and count mismatches.	True
indent_size	Optional[int]	Expected spaces per indentation level (default 2).	None
indent	Optional[int]	Deprecated alias of indent_size.	None

Returns:

Type	Description
Any	The decoded Python object (dict, list, or primitive).

Raises:

Type	Description
ToonDecodeError	If the input is malformed. Subclass of ValueError; carries .line (1-based) and .source (raw line) attributes.
ValueError	If an option value is invalid.

Example

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

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

Convert a TOON formatted string to a JSON formatted string.

The conversion goes through the standard library json module, so the result matches json.dumps(toons.loads(s), indent=indent).

Parameters:

Name	Type	Description	Default
s	str	String containing TOON data.	required
strict	bool	If True (default), enforce strict TOON v4.1 compliance.	True
indent_size	Optional[int]	Expected spaces per TOON indentation level (default 2).	None
indent	Optional[int]	Spaces per JSON indentation level, or None (default) for compact JSON.	None

Returns:

Type	Description
str	The JSON representation of the decoded data.

Raises:

Type	Description
ToonDecodeError	If the input is malformed. See loads.
ValueError	If an option value is invalid.

Example

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