Python TOON

https://github.com/xaviviro/python-toon
Admin
Python TOON is an encoder/decoder for Token-Oriented Object Notation (TOON), a compact data format...
Tokens:26,747
Snippets:351
Trust Score:8.8
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Setup and Test the Project

Source: https://github.com/xaviviro/python-toon/blob/main/CONTRIBUTING.md

Commands to clone the repository, install dependencies, and execute tests using uv.

```bash
# Clone the repository
git clone https://github.com/toon-format/toon-python.git
cd toon-python

# Install dependencies (uv will create a virtual environment automatically)
uv sync

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=src/toon --cov-report=term-missing
```

--------------------------------

### Install python-toon

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/INDEX.md

Command to install the library via pip.

```bash
pip install python-toon
```

--------------------------------

### Install build tools

Source: https://github.com/xaviviro/python-toon/blob/main/CONF.md

Install the necessary tools for building and uploading Python packages.

```bash
pip install build twine
```

--------------------------------

### String Quoting Examples

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/format-specification.md

Examples of when to quote strings based on content.

```text
name: Alice           # Unquoted
city: New York        # Unquoted (internal space OK)
empty: ""             # Quoted (empty)
keyword: "null"       # Quoted (keyword)
number: "42"          # Quoted (looks like number)
special: "hello:world"  # Quoted (contains colon)
```

--------------------------------

### Setup development environment with pip

Source: https://github.com/xaviviro/python-toon/blob/main/README.md

Alternative approach using standard pip and venv for dependency management.

```bash
# Clone the repository
git clone https://github.com/toon-format/toon-python.git
cd toon-python

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Install development dependencies
pip install -r requirements-dev.txt
```

--------------------------------

### Indentation Example

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/format-specification.md

Demonstration of nesting depth via indentation.

```text
root:
  level1:
    level2:
      level3: value
```

--------------------------------

### Setup development environment with uv

Source: https://github.com/xaviviro/python-toon/blob/main/README.md

Recommended approach for managing dependencies and virtual environments using the uv tool.

```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/toon-format/toon-python.git
cd toon-python

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install package in editable mode with dev dependencies
uv pip install -e ".[dev]"
```

--------------------------------

### Use push Method

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-writer.md

Example of adding lines at varying indentation depths and generating the final string.

```python
from toon.writer import LineWriter

writer = LineWriter(indent_size=2)

# Root level (depth 0)
writer.push(0, "name: Alice")

# One level deep (depth 1)
writer.push(1, "debug: true")
writer.push(1, "port: 8080")

# Two levels deep (depth 2)
writer.push(2, "key: value")

output = writer.to_string()
print(output)
# Output:
# name: Alice
#   debug: true
#   port: 8080
#     key: value
```

--------------------------------

### CLI Error Handling Example

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-cli.md

Demonstrates the output format when the CLI encounters a file error.

```bash
$ toon nonexistent.json
Error: Input file not found: nonexistent.json
```

--------------------------------

### CLI Conversion Commands

Source: https://github.com/xaviviro/python-toon/blob/main/README.md

Examples of using the toon command-line tool for file conversion, stream processing, and configuration overrides.

```bash
# Encode JSON to TOON (auto-detected by .json extension)
toon input.json -o output.toon

# Decode TOON to JSON (auto-detected by .toon extension)
toon data.toon -o output.json

# Use stdin/stdout
echo '{"name": "Ada"}' | toon -
# Output: name: Ada

# Force encode mode
toon data.json --encode

# Force decode mode
toon data.toon --decode

# Custom delimiter
toon data.json --delimiter "\t" -o output.toon

# With length markers
toon data.json --length-marker -o output.toon

# Lenient decoding (disable strict validation)
toon data.toon --no-strict -o output.json
```

--------------------------------

### Use to_string Method

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-writer.md

Example of joining accumulated lines and handling trailing newline requirements.

```python
from toon.writer import LineWriter

writer = LineWriter(indent_size=2)
writer.push(0, "key1: value1")
writer.push(0, "key2: value2")

output = writer.to_string()
# "key1: value1\nkey2: value2"

# To get the output with a trailing newline:
output_with_trailing = writer.to_string() + "\n"
```

--------------------------------

### Normalization examples

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-normalize.md

Demonstrates normalization of various Python types including primitives, collections, dates, and custom objects.

```python
from toon.normalize import normalize_value
from datetime import datetime, date
from decimal import Decimal
import math

# Primitives
normalize_value(42)           # 42
normalize_value("hello")      # "hello"
normalize_value(True)         # True

# Special numbers
normalize_value(float('inf'))   # None
normalize_value(float('nan'))   # None
normalize_value(-0)             # 0

# Decimal
normalize_value(Decimal("3.14"))  # 3.14

# Dates
normalize_value(date(2024, 1, 15))
# "2024-01-15"

normalize_value(datetime(2024, 1, 15, 14, 30, 0))
# "2024-01-15T14:30:00"

# Collections
normalize_value([1, 2, 3])                 # [1, 2, 3]
normalize_value((1, 2, 3))                 # [1, 2, 3] (converted to list)
normalize_value({1, 2, 3})                 # [1, 2, 3] (converted to list)

# Dict with non-string keys
normalize_value({1: "a", 2: "b"})
# {"1": "a", "2": "b"} (keys converted to strings)

# Nested structures
normalize_value({
    "dates": [date(2024, 1, 1), datetime(2024, 1, 1, 12, 0)],
    "number": Decimal("3.14"),
})
# {
#   "dates": ["2024-01-01", "2024-01-01T12:00:00"],
#   "number": 3.14
# }

# Callables
def my_func():
    pass

normalize_value(my_func)      # None
normalize_value(lambda x: x)  # None

# Custom objects
class User:
    def __init__(self, name):
        self.name = name

normalize_value(User("Alice"))  # None
```

--------------------------------

### Use is_array_of_arrays

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-normalize.md

Examples demonstrating array-of-arrays validation.

```python
from toon.normalize import is_array_of_arrays

is_array_of_arrays([[1, 2], [3, 4]])        # True
is_array_of_arrays([[], [1], [1, 2]])       # True (empty arrays OK)
is_array_of_arrays([1, [2, 3]])             # False (contains primitive)
is_array_of_arrays([{"a": [1]}])            # False (contains object)
is_array_of_arrays([])                      # True (empty is all arrays)
```

--------------------------------

### JSON Output Format

Source: https://github.com/xaviviro/python-toon/blob/main/README.md

Standard JSON representation of the user data used in the efficiency example.

```json
{"users": [{"id": 1, "name": "Alice", "age": 30, "active": true}, {"id": 2, "name": "Bob", "age": 25, "active": true}, {"id": 3, "name": "Charlie", "age": 35, "active": false}]}
```

--------------------------------

### Use is_array_of_objects

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-normalize.md

Examples demonstrating object-in-list validation.

```python
from toon.normalize import is_array_of_objects

is_array_of_objects([{"a": 1}, {"b": 2}])   # True
is_array_of_objects([{}, {"a": 1}])         # True (empty objects OK)
is_array_of_objects([1, {"a": 2}])          # False (contains primitive)
is_array_of_objects([{"a": [1, 2]}])        # True (objects can contain arrays)
is_array_of_objects([])                     # True (empty is all objects)
```

--------------------------------

### Use is_array_of_primitives

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-normalize.md

Examples demonstrating primitive type validation in lists.

```python
from toon.normalize import is_array_of_primitives

is_array_of_primitives([1, 2, 3])           # True
is_array_of_primitives([1, "a", True])      # True (mixed primitives OK)
is_array_of_primitives([1, [2], 3])         # False (contains array)
is_array_of_primitives([{"a": 1}])          # False (contains object)
is_array_of_primitives([])                  # True (empty is all primitives)
```

--------------------------------

### Encoding complex data structures

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/INDEX.md

Examples of how tabular arrays, primitive arrays, and nested objects are represented in TOON.

```python
# Tabular arrays (uniform objects)
users = [
	{"id": 1, "name": "Alice"},
	{"id": 2, "name": "Bob"},
]
print(encode(users))
# [2,]{id,name}:
#   1,Alice
#   2,Bob

# Primitive arrays
tags = ["alpha", "beta", "gamma"]
print(encode(tags))
# [3]: alpha,beta,gamma

# Nested objects
config = {
	"server": {"host": "localhost", "port": 8080}
}
print(encode(config))
# server:
#   host: localhost
#   port: 8080
```

--------------------------------

### Build the package

Source: https://github.com/xaviviro/python-toon/blob/main/CONF.md

Generate distribution files for the package.

```bash
python -m build
```

--------------------------------

### Catch ToonDecodeError

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/errors.md

Example of handling decoding errors when processing malformed input.

```python
from toon import decode, ToonDecodeError

try:
    result = decode(malformed_toon)
except ToonDecodeError as e:
    print(f"TOON parse error: {e}")
```

--------------------------------

### Configure CLI options

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Shows how to pass configuration flags via the command-line interface.

```bash
toon input.json -o output.toon \
  --indent 4 \
  --delimiter "|" \
  --length-marker
```

--------------------------------

### Use DecodeOptions for Decoding

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/types.md

Shows how to instantiate and use DecodeOptions with the decode function.

```python
from toon import decode, DecodeOptions

# Default options (strict mode, 2-space indent)
result = decode(toon_str)

# Custom options
options = DecodeOptions(indent=4, strict=False)
result = decode(toon_str, options)

# Accessing attributes
print(options.indent)   # 4
print(options.strict)   # False
```

--------------------------------

### Run Test Suite

Source: https://github.com/xaviviro/python-toon/blob/main/CONTRIBUTING.md

Command to execute the full test suite.

```bash
uv run pytest tests/
```

--------------------------------

### Run linting

Source: https://github.com/xaviviro/python-toon/blob/main/README.md

Check code style and quality using ruff.

```bash
ruff check src/toon tests
```

--------------------------------

### Decode objects recursively

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-decode.md

Decodes an object structure from a list of lines starting at a specific index and depth.

```python
def decode_object(
    lines: List[Line],
    start_idx: int,
    parent_depth: int,
    strict: bool
) -> Dict[str, Any]
```

--------------------------------

### Combined Options

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-cli.md

Apply multiple configuration flags simultaneously.

```bash
# Encode with tab delimiter, 4-space indent, and length markers
toon data.json \
  --encode \
  --delimiter "\t" \
  --indent 4 \
  --length-marker \
  -o output.toon
```

--------------------------------

### Configure default encoding and decoding

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Demonstrates the default configuration parameters used when optional arguments are omitted in encode and decode functions.

```python
from toon import encode, decode, DecodeOptions

# Encoding with defaults
result = encode(data)
# Equivalent to:
result = encode(data, {
    "indent": 2,
    "delimiter": ",",
    "lengthMarker": False,
})

# Decoding with defaults
result = decode(toon_str)
# Equivalent to:
result = decode(toon_str, DecodeOptions(indent=2, strict=True))
```

--------------------------------

### Basic Command Syntax

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-cli.md

General usage pattern for the toon command.

```bash
toon <input> [options]
```

--------------------------------

### Initialize DecodeOptions

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Basic usage of DecodeOptions to configure the decoder.

```python
from toon import decode, DecodeOptions

options = DecodeOptions(indent=2, strict=True)
result = decode(toon_str, options)
```

--------------------------------

### Encode keys with encode_key

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-primitives.md

Encodes a key string, returning it as-is if it matches the identifier format, or quoted if it contains invalid characters or starts with a number.

```python
from toon.primitives import encode_key

# Unquoted (valid identifiers)
encode_key("name")                  # "name"
encode_key("user_id")               # "user_id"
encode_key("_private")              # "_private"
encode_key("config.debug")          # "config.debug"
encode_key("User123")               # "User123"

# Quoted (invalid identifiers)
encode_key("123invalid")            # "\"123invalid\"" (starts with number)
encode_key("my-key")                # "\"my-key\"" (contains hyphen)
encode_key("my key")                # "\"my key\"" (contains space)
encode_key("key:value")             # "\"key:value\"" (contains colon)
```

--------------------------------

### Using the command-line interface

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/INDEX.md

Perform encoding and decoding operations directly from the terminal.

```bash
# Encode JSON to TOON
toon data.json -o output.toon

# Decode TOON to JSON
toon data.toon -o output.json

# Use stdin/stdout
echo '{"name": "Ada"}' | toon - -o output.toon
```

--------------------------------

### Upload to PyPI

Source: https://github.com/xaviviro/python-toon/blob/main/CONF.md

Upload the built package to the production PyPI repository.

```bash
twine upload dist/*
```

--------------------------------

### Accumulate output with LineWriter

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-writer.md

Demonstrates basic usage of LineWriter to push lines at specific indentation depths and retrieve the final string.

```python
from toon.writer import LineWriter

# The encoder creates a writer
writer = LineWriter(indent_size=2)

# Encodes add lines at appropriate depths
writer.push(0, "users[2,]{id,name}:")
writer.push(1, "1,Alice")
writer.push(1, "2,Bob")

# The final output is retrieved as a string
toon_output = writer.to_string()
```

--------------------------------

### Set Delimiter Options

Source: https://github.com/xaviviro/python-toon/blob/main/README.md

Demonstrates how to use different delimiters for array serialization.

```python
data = [1, 2, 3, 4, 5]

# Comma (default)
print(encode(data))
# [5]: 1,2,3,4,5

# Tab
print(encode(data, {"delimiter": "\t"}))
# [5	]: 1	2	3	4	5

# Pipe
print(encode(data, {"delimiter": "|"}))
# [5|]: 1|2|3|4|5
```

```python
encode(data, {"delimiter": "comma"})   # Default
encode(data, {"delimiter": "tab"})     # Tab-separated
encode(data, {"delimiter": "pipe"})    # Pipe-separated
```

--------------------------------

### Main CLI Entry Point Definition

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-cli.md

The primary entry point for the CLI application.

```python
def main() -> int
```

--------------------------------

### Encode Data with Options

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/INDEX.md

Demonstrates basic usage of the encode function with custom indentation options.

```python
from toon import encode, EncodeOptions

def convert(data: dict) -> str:
    opts: EncodeOptions = {"indent": 2}
    return encode(data, opts)
```

--------------------------------

### Build nested structures with LineWriter

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-writer.md

Illustrates building complex nested structures using multiple push calls with varying indentation levels.

```python
from toon.writer import LineWriter

writer = LineWriter(indent_size=2)

# Root object
writer.push(0, "metadata:")
writer.push(1, "version: 1")
writer.push(1, "author: test")

# Root array
writer.push(0, "items[2,]{id,name}:")
writer.push(1, "1,Item1")
writer.push(1, "2,Item2")

# Root array with nested items
writer.push(0, "tags[3]: alpha,beta,gamma")

result = writer.to_string()
print(result)
# metadata:
#   version: 1
#   author: test
# items[2,]{id,name}:
#   1,Item1
#   2,Item2
# tags[3]: alpha,beta,gamma
```

--------------------------------

### Configure for LLM integration

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Sets length markers to improve validation when generating TOON output with language models.

```python
from toon import encode, EncodeOptions

# Enable length markers for better validation
options: EncodeOptions = {
    "indent": 2,
    "delimiter": ",",
    "lengthMarker": "#",
}

toon_output = encode(data, options)

# Instruct the model:
# "Respond using TOON format. Array lengths are marked with [#N]."
# "Ensure array item counts match the declared length."
```

--------------------------------

### Run project tests

Source: https://github.com/xaviviro/python-toon/blob/main/README.md

Execute the test suite using pytest, optionally with coverage reporting.

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=toon --cov-report=term
```

--------------------------------

### Configure Encoding Options

Source: https://github.com/xaviviro/python-toon/blob/main/README.md

Customizes the output format using indentation, delimiters, and length markers.

```python
from toon import encode

encode(data, {
    "indent": 2,           # Spaces per indentation level (default: 2)
    "delimiter": ",",      # Delimiter for arrays: "," | "\t" | "|" (default: ",")
    "lengthMarker": "#"    # Optional marker prefix: "#" | False (default: False)
})
```

--------------------------------

### Upload to TestPyPI

Source: https://github.com/xaviviro/python-toon/blob/main/CONF.md

Upload the built package to the TestPyPI repository for testing purposes.

```bash
twine upload --repository testpypi dist/*
```

--------------------------------

### toon <input> [options]

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-cli.md

The primary command for converting files or streaming data between JSON and TOON formats.

```APIDOC
## CLI Command: toon

### Description
Converts input data between JSON and TOON formats. The tool supports auto-detection of the format based on file extensions or content, or explicit mode selection.

### Syntax
`toon <input> [options]`

### Arguments
- **input** (str) - Required - Input file path or '-' for stdin.

### Options
- **-o, --output** (str) - Optional - Output file path. If omitted, prints to stdout.
- **-e, --encode** (bool) - Optional - Force encode mode (JSON to TOON).
- **-d, --decode** (bool) - Optional - Force decode mode (TOON to JSON).
- **--delimiter** (str) - Optional - Array delimiter: ',' (comma), '\t' (tab), '|' (pipe). Default: ','
- **--indent** (int) - Optional - Indentation size in spaces. Default: 2
- **--length-marker** (bool) - Optional - Add '#' prefix to array lengths (e.g., [#3]).
- **--no-strict** (bool) - Optional - Disable strict validation when decoding.
```

--------------------------------

### DecodeOptions Constructor

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Initializes the configuration options for the decode function.

```APIDOC
## DecodeOptions(indent: int = 2, strict: bool = True)

### Description
Initializes a new instance of the DecodeOptions class to configure the decoding process.

### Parameters
- **indent** (int) - Optional - Expected number of spaces per indentation level. Defaults to 2.
- **strict** (bool) - Optional - Enable strict validation (True) or lenient mode (False). Defaults to True.

### Usage Example
```python
from toon import decode, DecodeOptions

options = DecodeOptions(indent=2, strict=True)
result = decode(toon_str, options)
```
```

--------------------------------

### Convert formats via CLI

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/README.md

Converts between JSON and TOON formats using the command line interface.

```bash
toon input.json -o output.toon
toon output.toon -o recovered.json
```

--------------------------------

### Configure custom delimiter

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-encode.md

Using alternative delimiters like tabs or specific string keys.

```python
# Use tab delimiter instead of comma
data = [1, 2, 3, 4, 5]
result = encode(data, {"delimiter": "\t"})
print(result)
# Output:
# [5	]: 1	2	3	4	5

# Or use the string key "tab"
result = encode(data, {"delimiter": "tab"})
```

--------------------------------

### Importing Type Definitions

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/types.md

Import necessary type aliases and options from the toon library.

```python
from toon import EncodeOptions, DecodeOptions, Delimiter, DelimiterKey
from toon.types import (
    EncodeOptions,
    DecodeOptions,
    Delimiter,
    DelimiterKey,
    ResolvedEncodeOptions,
    JsonPrimitive,
    JsonObject,
    JsonArray,
    JsonValue,
)
```

--------------------------------

### Importing the toon API

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/INDEX.md

Access the primary functions, exceptions, and configuration types from the top-level package.

```python
from toon import (
	encode,                # Function: value → TOON string
	decode,                # Function: TOON string → value
	ToonDecodeError,       # Exception: decoding errors
	EncodeOptions,         # Type: encoding configuration
	DecodeOptions,         # Class: decoding configuration
	Delimiter,             # Type: delimiter string
	DelimiterKey,          # Type: delimiter key literal
)
```

--------------------------------

### Persist configuration across operations

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Define EncodeOptions and DecodeOptions objects to reuse settings across multiple encoding and decoding cycles.

```python
from toon import encode, decode, DecodeOptions, EncodeOptions

# Encode configuration
encode_opts: EncodeOptions = {
    "indent": 4,
    "delimiter": "tab",
    "lengthMarker": "#",
}

# Decode configuration
decode_opts = DecodeOptions(indent=4, strict=False)

# Use across operations
for data in datasets:
    toon = encode(data, encode_opts)
    result = decode(toon, decode_opts)
```

--------------------------------

### Define to_string Method

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-writer.md

Method signature for retrieving the accumulated output as a single string.

```python
def to_string(self) -> str
```

--------------------------------

### Import Internal Primitives

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-primitives.md

Import the necessary primitive encoding utilities for internal module use.

```python
from toon.primitives import (
    encode_primitive,
    encode_string_literal,
    encode_key,
    escape_string,
    is_safe_unquoted,
    join_encoded_values,
    format_header,
)
```

--------------------------------

### Import LineWriter

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-writer.md

Import the internal utility class for use in extending the library.

```python
from toon.writer import LineWriter
```

--------------------------------

### Combine multiple encoding options

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Apply multiple configuration settings simultaneously to control indentation, delimiters, and length markers in a single encode call.

```python
from toon import encode

data = {
	"users": [
		{"id": 1, "name": "Alice"},
		{"id": 2, "name": "Bob"},
	]
}

result = encode(data, {
	"indent": 4,
	"delimiter": "pipe",
	"lengthMarker": "#",
})

print(result)
# users[#2|]{id,name}:
#     1|Alice
#     2|Bob
```

--------------------------------

### Implementing error recovery with DecodeOptions

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/errors.md

Use DecodeOptions to toggle strict parsing and implement fallback logic when decoding fails.

```python
from toon import decode, DecodeOptions, ToonDecodeError

def decode_with_recovery(toon_str):
    """Try to parse, use lenient mode on failure."""
    try:
        # Attempt strict parse
        return ("success", decode(toon_str, DecodeOptions(strict=True)))
    
    except ToonDecodeError as e:
        # On failure, try lenient
        try:
            lenient_result = decode(toon_str, DecodeOptions(strict=False))
            return ("recovered", lenient_result)
        except Exception:
            # Even lenient parsing failed
            return ("failed", str(e))
```

--------------------------------

### CLI Usage for TOON

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/README.md

Command-line interface commands for encoding and decoding files with various options.

```bash
# Encode JSON to TOON
toon data.json -o output.toon

# Decode TOON to JSON
toon data.toon -o output.json

# With options
toon data.json --indent 4 --delimiter "|" --length-marker -o out.toon
```

--------------------------------

### Encode Python Objects to TOON

Source: https://github.com/xaviviro/python-toon/blob/main/README.md

Demonstrates encoding simple dictionaries, tabular arrays, and complex nested structures using the encode function.

```python
from toon import encode

# Simple object
data = {"name": "Alice", "age": 30}
print(encode(data))
# Output:
# name: Alice
# age: 30

# Tabular array (uniform objects)
users = [
    {"id": 1, "name": "Alice", "age": 30},
    {"id": 2, "name": "Bob", "age": 25},
    {"id": 3, "name": "Charlie", "age": 35},
]
print(encode(users))
# Output:
# [3,]{id,name,age}:
#   1,Alice,30
#   2,Bob,25
#   3,Charlie,35

# Complex nested structure
data = {
    "metadata": {"version": 1, "author": "test"},
    "items": [
        {"id": 1, "name": "Item1"},
        {"id": 2, "name": "Item2"},
    ],
    "tags": ["alpha", "beta", "gamma"],
}
print(encode(data))
# Output:
# metadata:
#   version: 1
#   author: test
# items[2,]{id,name}:
#   1,Item1
#   2,Item2
# tags[3]: alpha,beta,gamma
```

--------------------------------

### Length Markers

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-cli.md

Enable the addition of a # prefix to array lengths.

```bash
# Add # prefix to array lengths
toon data.json --length-marker -o output.toon

# Output will have: [#3,]{id,name,email}:
# Instead of:      [3,]{id,name,email}:
```

--------------------------------

### Run Type Checking

Source: https://github.com/xaviviro/python-toon/blob/main/CONTRIBUTING.md

Command to verify type safety using mypy.

```bash
uv run mypy src/
```

--------------------------------

### Object Key-Value Pairs

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/format-specification.md

Basic object structure using key-value pairs separated by colons.

```text
key: value
another_key: another_value
```

--------------------------------

### Define LineWriter Class

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-writer.md

Initializes the LineWriter with a specified number of spaces per indentation level.

```python
class LineWriter:
    """Manages indented text output."""

    def __init__(self, indent_size: int) -> None:
        """Initialize the line writer.

        Args:
            indent_size: Number of spaces per indentation level
        """
        self._lines: List[str] = []
        self._indentation_string = " " * indent_size
```

--------------------------------

### Define push Method

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-writer.md

Method signature for adding lines with specific indentation depth.

```python
def push(self, depth: int, content: str) -> None
```

--------------------------------

### Lint and Format Code

Source: https://github.com/xaviviro/python-toon/blob/main/CONTRIBUTING.md

Commands to check and format code using ruff.

```bash
uv run ruff check src/ tests/
uv run ruff format src/ tests/
```

--------------------------------

### Importing decode and DecodeOptions

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-decode.md

Required imports for using the TOON decoding functionality.

```python
from toon import decode, DecodeOptions
```

--------------------------------

### encode(data, options)

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Encodes data into the toon format using optional configuration parameters to control formatting.

```APIDOC
## encode(data, options)

### Description
Encodes a Python object into the toon format. The optional `options` parameter allows customization of the output structure.

### Parameters
- **data** (Any) - Required - The data structure to encode.
- **options** (EncodeOptions) - Optional - Configuration dictionary.

#### EncodeOptions Fields
- **indent** (int) - Optional - Number of spaces per indentation level (Default: 2).
- **delimiter** (str) - Optional - Character used to separate array elements. Valid values: ",", "\t", "|", "comma", "tab", "pipe" (Default: ",").
- **lengthMarker** (str|bool) - Optional - Add '#' prefix to array length markers. Valid values: "#" or False (Default: False).

### Example
```python
from toon import encode

result = encode(data, {
    "indent": 4,
    "delimiter": "pipe",
    "lengthMarker": "#"
})
```
```

--------------------------------

### format_header(key, length, fields, delimiter, length_marker)

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-primitives.md

Formats an array header string according to the TOON specification.

```APIDOC
## format_header(key, length, fields, delimiter, length_marker)

### Description
Formats an array header according to TOON specification, supporting tabular and primitive arrays.

### Parameters
- **key** (Optional[str]) - Required - Optional key name for keyed arrays
- **length** (int) - Required - Array length
- **fields** (Optional[List[str]]) - Required - Field names for tabular arrays, or None for non-tabular
- **delimiter** (str) - Required - Delimiter character used in the array
- **length_marker** (Optional[str]) - Required - Optional "#" prefix for length, or None/False

### Returns
- **str** - Formatted header
```

--------------------------------

### Enable length markers

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-encode.md

Adding a length prefix to array structures.

```python
# Add # prefix to array lengths
users = [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"},
]
result = encode(users, {"lengthMarker": "#"})
print(result)
# Output:
# [#2,]{id,name}:
#   1,Alice
#   2,Bob
```

--------------------------------

### Define EncodeOptions for encoding

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Pass an EncodeOptions dictionary to the encode function to customize output formatting.

```python
from toon import encode, EncodeOptions

options: EncodeOptions = {
	"indent": 2,
	"delimiter": ",",
	"lengthMarker": "#",
}

result = encode(data, options)
```

--------------------------------

### Format Objects

Source: https://github.com/xaviviro/python-toon/blob/main/README.md

Represent key-value pairs with primitives or nested structures.

```python
{"name": "Alice", "age": 30}
# =>
# name: Alice
# age: 30
```

--------------------------------

### Configure Decoding Options

Source: https://github.com/xaviviro/python-toon/blob/main/README.md

Uses DecodeOptions to control indentation and strict validation during parsing.

```python
from toon import decode, DecodeOptions

options = DecodeOptions(
    indent=2,    # Expected number of spaces per indentation level (default: 2)
    strict=True  # Enable strict validation (default: True)
)

data = decode(toon_str, options)
```

--------------------------------

### Configure Strict Mode

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Handling validation errors by toggling the strict parameter.

```python
from toon import decode, DecodeOptions, ToonDecodeError

malformed_toon = "[3]: 1,2"  # Says 3 elements but only has 2

# Strict mode (default)
try:
    result = decode(malformed_toon, DecodeOptions(strict=True))
except ToonDecodeError as e:
    print(e)  # Expected 3 values, but got 2

# Lenient mode
result = decode(malformed_toon, DecodeOptions(strict=False))
print(result)  # [1, 2] (mismatched length ignored)
```

--------------------------------

### Enable array length markers

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Add a '#' prefix to array length declarations to assist in programmatic validation or LLM prompting.

```python
from toon import encode

users = [
	{"id": 1, "name": "Alice"},
	{"id": 2, "name": "Bob"},
]

# Without marker (default)
print(encode(users))
# [2,]{id,name}:
#   1,Alice
#   2,Bob

# With marker
print(encode(users, {"lengthMarker": "#"}))
# [#2,]{id,name}:
#   1,Alice
#   2,Bob
```

--------------------------------

### Configure Indentation

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Adjusting the indent parameter to match the input string's indentation level.

```python
from toon import decode, DecodeOptions

toon_str = """config:
    server:
        port: 8080"""

# Expected 2-space indentation
result = decode(toon_str, DecodeOptions(indent=4))
# Parses correctly (indentation is 4 spaces)

toon_str = """config:
  server:
    port: 8080"""

# If you expect 2-space indentation (default)
result = decode(toon_str)  # Works
```

--------------------------------

### Manually Encode Tabular Data

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-primitives.md

Demonstrates building a tabular array by manually invoking encoding and formatting primitives.

```python
from toon.primitives import encode_primitive, encode_key, join_encoded_values, format_header

# Build a tabular array manually
header = format_header("users", 2, ["id", "name"], ",", None)
row1 = join_encoded_values([encode_primitive(1), encode_primitive("Alice")], ",")
row2 = join_encoded_values([encode_primitive(2), encode_primitive("Bob")], ",")

output = f"{header}\n  {row1}\n  {row2}"
print(output)
# Output:
# users[2,]{id,name}:
#   1,Alice
#   2,Bob
```

--------------------------------

### Define a simple object in TOON

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/format-specification.md

Represents a flat key-value structure.

```text
name: Alice
age: 30
active: true
```

```json
{
  "name": "Alice",
  "age": 30,
  "active": true
}
```

--------------------------------

### Import Exported Types

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/README.md

List of available types and exceptions for type hinting and error handling.

```python
from toon import (
    EncodeOptions,      # TypedDict: indent, delimiter, lengthMarker
    DecodeOptions,      # Class: indent, strict
    Delimiter,          # Type: str
    DelimiterKey,       # Type: Literal["comma", "tab", "pipe"]
    ToonDecodeError,    # Exception class
)
```

--------------------------------

### Enforce type safety for configurations

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Use type annotations like DelimiterKey to ensure configuration values are valid during development.

```python
from toon import encode, EncodeOptions, DelimiterKey

def convert(data: dict, delim: DelimiterKey) -> str:
    opts: EncodeOptions = {
        "delimiter": delim,
        "indent": 2,
    }
    return encode(data, opts)

# Type checker ensures valid delimiter
result = convert(data, "tab")  # ✓ Valid
# result = convert(data, "semicolon")  # ✗ Type error
```

--------------------------------

### Basic Object Decoding

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-decode.md

Decodes a simple key-value TOON string into a Python dictionary.

```python
from toon import decode

toon_str = """name: Alice
age: 30"""

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

--------------------------------

### Configure Strict Decoding Mode

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/errors.md

Enables strict mode to force exceptions on format violations like array length mismatches or missing syntax.

```python
from toon import decode, DecodeOptions, ToonDecodeError

options = DecodeOptions(strict=True)

try:
    # Array length mismatch
    result = decode("[3]: 1,2", options)
except ToonDecodeError as e:
    print(e)  # "Expected 3 values, but got 2"

try:
    # Missing colon
    result = decode("key value", options)
except ToonDecodeError as e:
    print(e)  # "Missing colon after key"
```

--------------------------------

### Nested Objects

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/format-specification.md

Nesting is achieved through indentation.

```text
user:
  id: 123
  profile:
    name: Alice
    age: 30
```

--------------------------------

### Custom Indentation

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-cli.md

Adjust the indentation size in spaces for output files.

```bash
# Encode with 4-space indentation
toon data.json --indent 4 -o output.toon

# Decode respecting 4-space indentation
toon data.toon --indent 4 --decode -o output.json
```

--------------------------------

### Format array headers with format_header

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-primitives.md

Generates a TOON-compliant array header string based on key, length, fields, delimiter, and optional length markers.

```python
from toon.primitives import format_header

# Root primitive array
format_header(None, 5, None, ",", None)
# "[5]:"

# Root primitive array with tab delimiter
format_header(None, 5, None, "\t", None)
# "[5\t]:"

# With length marker
format_header(None, 5, None, ",", "#")
# "[#5]:"

# Keyed primitive array
format_header("items", 3, None, ",", None)
# "items[3]:"

# Tabular array
format_header("users", 2, ["id", "name"], ",", None)
# "users[2,]{id,name}:"

# Tabular with pipe delimiter and marker
format_header("data", 3, ["a", "b"], "|", "#")
# "data[#3|]{a,b}:"
```

--------------------------------

### Define a primitive array in TOON

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/format-specification.md

Uses bracket notation to define array size and values.

```text
numbers[5]: 1,2,3,4,5
```

```json
{
  "numbers": [1, 2, 3, 4, 5]
}
```

--------------------------------

### Import normalize_value

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-normalize.md

Import the primary normalization function from the toon.normalize module.

```python
from toon.normalize import normalize_value
```

--------------------------------

### Type Checking with MyPy

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/types.md

Demonstrates using EncodeOptions for type-safe encoding of dictionary data.

```python
from toon import encode, EncodeOptions

def convert_to_toon(data: dict, delimiter: str) -> str:
    options: EncodeOptions = {
        "delimiter": delimiter,
        "indent": 2,
    }
    return encode(data, options)

result = convert_to_toon({"name": "Alice"}, ",")
```

--------------------------------

### TOON Output Format

Source: https://github.com/xaviviro/python-toon/blob/main/README.md

TOON representation of the user data using tabular format for uniform arrays.

```text
users[3,]{id,name,age,active}:
  1,Alice,30,true
  2,Bob,25,true
  3,Charlie,35,false
```

--------------------------------

### Enable Length Markers

Source: https://github.com/xaviviro/python-toon/blob/main/README.md

Include a length marker in the encode function to help LLMs validate array sizes.

```python
encode(data, {"lengthMarker": "#"})
```

--------------------------------

### Strict vs. Lenient Decoding

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/types.md

Configures decoding behavior using DecodeOptions to either raise exceptions or skip errors during parsing.

```python
from toon import decode, DecodeOptions

# Strict: throws on errors
options_strict = DecodeOptions(indent=2, strict=True)
try:
    result = decode(malformed_toon, options_strict)
except Exception as e:
    print(f"Parse failed: {e}")

# Lenient: silently skips errors
options_lenient = DecodeOptions(indent=2, strict=False)
result = decode(malformed_toon, options_lenient)
```

--------------------------------

### Stdin/Stdout Streaming

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-cli.md

Process data via standard input and output streams.

```bash
# Pipe JSON to stdin, print TOON to stdout
echo '{"name": "Ada", "age": 30}' | toon -
# Output:
# name: Ada
# age: 30

# Decode from stdin
echo 'name: Ada\nage: 30' | toon - --decode
# Output:
# {
#   "name": "Ada",
#   "age": 30
# }
```

--------------------------------

### Encode data for LLM integration

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/README.md

Uses the lengthMarker option to provide explicit array size hints for LLM instructions.

```python
from toon import encode

data = {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
toon_str = encode(data, {"lengthMarker": "#"})
# Instruct model: "Arrays marked with [#N] must have exactly N items."
```

--------------------------------

### Programmatic usage of encode and decode functions

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-cli.md

Import encode_json_to_toon and decode_toon_to_json to process data within Python scripts.

```python
from toon.cli import encode_json_to_toon, decode_toon_to_json

# Encode
json_input = '{"items": [1, 2, 3]}'
toon_output = encode_json_to_toon(json_input, delimiter="|")

# Decode
toon_input = "items[3|]: 1|2|3"
json_output = decode_toon_to_json(toon_input, indent=2, strict=False)
print(json_output)
```

--------------------------------

### Configure custom indentation

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-encode.md

Adjusting the number of spaces used for indentation.

```python
# Use 4 spaces per indentation level
data = {
    "config": {
        "debug": True,
        "port": 8080,
    }
}
result = encode(data, {"indent": 4})
print(result)
# Output:
# config:
#     debug: true
#     port: 8080
```

--------------------------------

### Define a tabular array in TOON

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/format-specification.md

Uses a header definition with keys to map rows into an array of objects.

```text
users[3,]{id,name,email}:
  1,Alice,alice@example.com
  2,Bob,bob@example.com
  3,Charlie,charlie@example.com
```

```json
{
  "users": [
    {"id": 1, "name": "Alice", "email": "alice@example.com"},
    {"id": 2, "name": "Bob", "email": "bob@example.com"},
    {"id": 3, "name": "Charlie", "email": "charlie@example.com"}
  ]
}
```

--------------------------------

### encode_json_to_toon(json_input, delimiter)

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-cli.md

Encodes a JSON string into the Toon format.

```APIDOC
## encode_json_to_toon(json_input, delimiter)

### Description
Converts a JSON formatted string into the Toon representation.

### Parameters
- **json_input** (string) - Required - The JSON string to encode.
- **delimiter** (string) - Optional - The character used as a delimiter in the output.

### Example
```python
from toon.cli import encode_json_to_toon
toon_output = encode_json_to_toon('{"items": [1, 2, 3]}', delimiter="|")
```
```

--------------------------------

### Manual Encoding Functions

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-primitives.md

Functions for manually constructing tabular data structures and formatting headers.

```APIDOC
## toon.primitives Encoding Functions

### Description
These functions allow for the manual construction of tabular data formats, including header generation and value joining.

### Functions
- **format_header(name, count, columns, delimiter, metadata)**: Creates a header string for a tabular data block.
- **encode_primitive(value)**: Encodes a single value into the toon primitive format.
- **join_encoded_values(values, delimiter)**: Joins a list of encoded values into a single string using the specified delimiter.
```

--------------------------------

### Integrate LineWriter in encoder functions

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-writer.md

Shows how LineWriter is instantiated within an encoding function to handle recursive value processing.

```python
from toon.encoder import encode
from toon.writer import LineWriter
from toon.normalize import normalize_value
from toon.encoders import encode_value
from toon.types import ResolvedEncodeOptions

# Inside the encode() function:
def encode(value, options=None):
    normalized = normalize_value(value)
    resolved_options = resolve_options(options)
    
    # Create writer
    writer = LineWriter(resolved_options.indent)
    
    # Recursively encode the value
    encode_value(normalized, resolved_options, writer, 0)
    
    # Retrieve final string
    return writer.to_string()
```

--------------------------------

### decode(toon_str, options=None)

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/api-reference-decode.md

Parses a TOON formatted string into a Python dictionary or list. The optional options parameter allows for configuration of indentation and strict parsing mode.

```APIDOC
## decode(toon_str, options=None)

### Description
Parses a TOON string into a Python object. Supports nested structures, arrays, and custom delimiters.

### Parameters
- **toon_str** (str) - Required - The TOON formatted string to decode.
- **options** (DecodeOptions) - Optional - Configuration object for decoding, including `indent` (int) and `strict` (bool).

### Usage Example
```python
from toon import decode

toon_str = """name: Alice
age: 30"""
result = decode(toon_str)
# Output: {'name': 'Alice', 'age': 30}
```
```

--------------------------------

### Implement Graceful Degradation

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/errors.md

Attempts a strict decode first, falling back to lenient mode if a parsing error occurs.

```python
from toon import decode, DecodeOptions, ToonDecodeError

def safe_decode(toon_str):
    """Try strict parsing, fall back to lenient."""
    try:
        return decode(toon_str, DecodeOptions(strict=True))
    except ToonDecodeError as e:
        print(f"Strict parse failed: {e}, retrying lenient")
        return decode(toon_str, DecodeOptions(strict=False))

result = safe_decode(malformed_toon)
```

--------------------------------

### Configure delimiter for data with commas

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Uses a tab delimiter to avoid issues when the source data contains commas.

```python
from toon import encode

# Data contains commas
sentences = [
    "Hello, world!",
    "How are you, today?",
]

# Tab delimiter prevents escaping
result = encode(sentences, {"delimiter": "tab"})
# [2	]: "Hello, world!","How are you, today?"
```

--------------------------------

### Configure indentation levels

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/configuration.md

Adjust the number of spaces used for nested structures or disable indentation entirely by setting indent to 0.

```python
from toon import encode

data = {
	"config": {
		"server": {
			"port": 8080
		}
	}
}

# Default: 2 spaces
print(encode(data))
# config:
#   server:
#     port: 8080

# Custom: 4 spaces
print(encode(data, {"indent": 4}))
# config:
#     server:
#         port: 8080

# No indentation
print(encode(data, {"indent": 0}))
# config:
# server:
# port: 8080
```

--------------------------------

### Decoding TOON to Python values

Source: https://github.com/xaviviro/python-toon/blob/main/_autodocs/INDEX.md

Parse a TOON formatted string back into native Python data structures.

```python
from toon import decode

toon_str = "name: Alice\nage: 30"
data = decode(toon_str)
print(data)  # {'name': 'Alice', 'age': 30}
```
Tokens:
Raw