Metadata-Version: 2.5
Name: toon-django
Version: 0.1.0
Summary: Token-Oriented Object Notation for Django applications
Project-URL: Documentation, https://github.com/hartungstenio/toon-django#readme
Project-URL: Issues, https://github.com/hartungstenio/toon-django/issues
Project-URL: Source, https://github.com/hartungstenio/toon-django
Author-email: Christian Hartung <6785871+hartungstenio@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Framework :: Django :: 6.1
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
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: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: django>=5.2
Requires-Dist: toon-format>=0.9.0b1
Requires-Dist: typing-extensions; python_version < '3.12'
Provides-Extra: dmr
Requires-Dist: django-modern-rest; extra == 'dmr'
Provides-Extra: drf
Requires-Dist: djangorestframework; extra == 'drf'
Provides-Extra: ninja
Requires-Dist: django-ninja; extra == 'ninja'
Description-Content-Type: text/markdown

# toon-django

[![PyPI - Version](https://img.shields.io/pypi/v/toon-django.svg)](https://pypi.org/project/toon-django)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/toon-django.svg)](https://pypi.org/project/toon-django)

Django integration for the [Token-Oriented Object Notation (TOON)](https://pypi.org/project/toon-format) format. Provides a `ToonResponse` for plain Django views and parsers/renderers for Django REST Framework, Django Ninja, and Django Modern REST, so you can accept and emit `text/toon` alongside your existing content types with minimal setup.

---

## Installation

The base package works with plain Django out of the box:

```console
pip install toon-django
```

Install optional extras for the frameworks you use:

```console
# Django Modern REST
pip install "toon-django[dmr]"

# Django Ninja
pip install "toon-django[ninja]"

# Django REST Framework
pip install "toon-django[drf]"
```

## Usage

### Plain Django

Use `ToonResponse` in any view the same way you would use `JsonResponse`:

```python
from toon_django.http import ToonResponse


def my_view(request):
    return ToonResponse({"hello": "world"})
```

Pass `safe=False` to serialize non-dict objects such as lists:

```python
def my_list_view(request):
    return ToonResponse([1, 2, 3], safe=False)
```

### Django Modern REST

Register `ToonParser` and `ToonRenderer` on a controller:

```python
from dmr.controller import Controller
from toon_django.contrib.dmr import ToonParser, ToonRenderer


class MyController(Controller):
    parsers = [ToonParser()]
    renderers = [ToonRenderer()]
```

### Django Ninja

Pass `ToonParser` and `ToonRenderer` to the `NinjaAPI` constructor:

```python
from ninja import NinjaAPI
from toon_django.contrib.ninja import ToonParser, ToonRenderer


api = NinjaAPI(parser=ToonParser(), renderer=ToonRenderer())
```

The API will then accept and emit `Content-Type: text/toon`.

### Django REST Framework

Register `ToonParser` and `ToonRenderer` on a view or viewset:

```python
from rest_framework.viewsets import ModelViewSet
from toon_django.contrib.rest_framework import ToonParser, ToonRenderer


class MyViewSet(ModelViewSet):
    parser_classes = [ToonParser]
    renderer_classes = [ToonRenderer]
```

The parser accepts `Content-Type: text/toon` requests; the renderer responds to `Accept: text/toon`.

You can also set them globally in `settings.py`:

```python
REST_FRAMEWORK = {
    "DEFAULT_PARSER_CLASSES": [
        "toon_django.contrib.rest_framework.ToonParser",
        "rest_framework.parsers.JSONParser",
    ],
    "DEFAULT_RENDERER_CLASSES": [
        "toon_django.contrib.rest_framework.ToonRenderer",
        "rest_framework.renderers.JSONRenderer",
    ],
}
```

## License

`toon-django` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
