Metadata-Version: 2.4
Name: toon-python
Version: 1.0.0rc1
Summary: Official Python implementation of TOON (Token-Oriented Object Notation), a compact, human-readable encoding of the JSON data model for LLM prompts.
Keywords: toon,serialization,llm,json,tokens,data-format
Author: Johann Schopplich, Alessio Sanfratello
Author-email: Johann Schopplich <hello@johannschopplich.com>, Alessio Sanfratello <sanfra90@gmail.com>
License-Expression: MIT
License-File: AUTHORS
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Classifier: Typing :: Typed
Requires-Dist: pydantic>=2 ; extra == 'pydantic'
Requires-Dist: tiktoken>=0.7 ; extra == 'tokens'
Requires-Python: >=3.10
Project-URL: Homepage, https://toonformat.dev
Project-URL: Documentation, https://toon-python.readthedocs.io
Project-URL: Repository, https://github.com/toon-format/toon-python
Project-URL: Specification, https://github.com/toon-format/spec/blob/main/SPEC.md
Project-URL: Changelog, https://github.com/toon-format/toon-python/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/toon-format/toon-python/issues
Provides-Extra: pydantic
Provides-Extra: tokens
Description-Content-Type: text/markdown

# TOON for Python

[![CI](https://github.com/toon-format/toon-python/actions/workflows/ci.yml/badge.svg)](https://github.com/toon-format/toon-python/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/toon-python.svg)](https://pypi.org/project/toon-python/)
[![Python versions](https://img.shields.io/pypi/pyversions/toon-python.svg)](https://pypi.org/project/toon-python/)
[![Docs](https://readthedocs.org/projects/toon-python/badge/?version=latest)](https://toon-python.readthedocs.io)
[![TOON spec](https://img.shields.io/badge/TOON%20spec-4.1-blue)](https://github.com/toon-format/spec/blob/main/SPEC.md)

The official Python implementation of **TOON** (Token-Oriented Object Notation):
a compact, human-readable encoding of the JSON data model, designed to save
tokens in LLM prompts.

- **Complete**: implements [TOON specification 4.1](https://github.com/toon-format/spec/blob/main/SPEC.md)
  and passes every official conformance fixture.
- **Familiar**: `dumps`, `dump`, `loads`, and `load`, like the `json` module.
- **Pure Python**, no dependencies, fully typed, Python 3.10+.

```python
import toon

data = {
    "context": {"task": "Our favorite hikes together", "location": "Boulder"},
    "friends": ["ana", "luis", "sam"],
    "hikes": [
        {"id": 1, "name": "Blue Lake Trail", "distanceKm": 7.5, "wasSunny": True},
        {"id": 2, "name": "Ridge Overlook", "distanceKm": 9.2, "wasSunny": False},
    ],
}

print(toon.dumps(data))
```

```
context:
  task: Our favorite hikes together
  location: Boulder
friends[3]: ana,luis,sam
hikes[2]{id,name,distanceKm,wasSunny}:
  1,Blue Lake Trail,7.5,true
  2,Ridge Overlook,9.2,false
```

```python
assert toon.loads(toon.dumps(data)) == data
```

## Installation

```bash
pip install toon-python
# or
uv add toon-python
```

The distribution is named `toon-python`; the module is `toon`. Optional extras:
`toon-python[pydantic]` for the Pydantic integration and `toon-python[tokens]`
for `toon --stats`. Up to 0.9 the distribution was `toon-format`, which still
works and installs `toon-python`.

## Usage

```python
toon.dumps(obj, *, indent_size=2, delimiter=",", default=None, sort_keys=False)
toon.loads(s, *, strict=True, indent_size=2, parse_float=None, parse_int=None,
           object_hook=None, object_pairs_hook=None)
```

`dump` and `load` do the same with files. Invalid documents raise
`toon.ToonDecodeError`, a `ValueError` that carries the `line` and `source` of
the error. The package also provides a `toon` command and a Pydantic integration:

```bash
toon data.json -o data.toon   # JSON to TOON
toon --check response.toon    # validate only
```

## Documentation

The full documentation is at
**[toon-python.readthedocs.io](https://toon-python.readthedocs.io)**: usage,
the Python type mapping, the choices the specification leaves to
implementations, the command line, Pydantic, and the API reference.

> [!NOTE]
> The documentation site is not published yet. Until it is, read the pages in
> [`docs/`](docs/) on GitHub.

## Migrating from `toon_format` 0.9

`pip install toon-format` and `import toon_format` still work: the
`toon-format` distribution now installs `toon-python`, and `toon_format`
delegates to the new API with a `DeprecationWarning`. See the [migration guide](https://toon-python.readthedocs.io/en/latest/migration/).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Project conventions for humans and coding
agents are in [AGENTS.md](AGENTS.md).

## Authors

The people who wrote this package are listed in [AUTHORS](AUTHORS); every
contributor is on the [contributors page](https://github.com/toon-format/toon-python/graphs/contributors).

## License

[MIT](LICENSE)
