Metadata-Version: 2.4
Name: django-reversion-rest-framework
Version: 4.1.0
Summary: A package for adding a django-reversion history endpoint to django-rest-framework ModelViewSet
Author-email: Denny Biasiolli <denny.biasiolli@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/dennybiasiolli/django-reversion-rest-framework
Project-URL: Bug Tracker, https://github.com/dennybiasiolli/django-reversion-rest-framework/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Framework :: Django
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django-reversion>=4
Requires-Dist: djangorestframework>=3
Dynamic: license-file

# django-reversion-rest-framework

A package for adding a django-reversion history endpoint to django-rest-framework ModelViewSet.


## Installation

```sh
pip install django-reversion-rest-framework
```


## Configuration

Follow the official website for the installation and the integration of django-reversion in your project, otherwise future steps won't work.

You might need to enable the `ReversionMiddleware` for storing a version for each API change.<br>
Follow the instructions [here](https://django-reversion.readthedocs.io/en/stable/middleware.html),
you should add `'reversion.middleware.RevisionMiddleware'` to your `MIDDLEWARE` setting.


### Using the HistoryModelViewSet

The `HistoryModelViewSet` extends django-rest-framework's `ModelViewSet` adding

- a GET `history` action in the detail (`/my-model-url/<pk>/history/`)

    displaying a list of all revisions of that specific record

- a GET `version` action in the history detail (`/my-model-url/<pk>/history/<version_pk>/`)

    displaying a specific revisions of that specific record

- a GET `deleted` action in the list (`/my-model-url/deleted/`)

    displaying a list of all deleted records

- a POST `revert` action in the detail (`/my-model-url/<pk>/revert/<version_pk>/`)

    allowing users to revert to a previous revision of the object

- a POST `restore` action in the list (`/my-model-url/restore/<version_pk>/`)

    allowing users to restore a deleted object from its version history

You can use the `HistoryModelViewSet` in place of the `ModelViewSet`
during viewsets definition.

```py
from reversion_rest_framework.viewsets import HistoryModelViewSet


class MyModelViewSet(HistoryModelViewSet):
    # ...
```

For advanced or selective implementation, you can use `reversion_rest_framework.mixins`.

- `HistoryMixin` contains `history` and `version` actions

- `DeletedMixin` contains only the `deleted` action

- `RestoreMixin` contains `deleted` and `restore` actions

- `RevertMixin` contains `history`, `version` and `revert` actions

```py
from rest_framework.viewsets import ModelViewSet
from reversion_rest_framework.mixins import HistoryMixin, DeletedMixin


class ReadOnlyHistoryViewSet(HistoryMixin, DeletedMixin, ModelViewSet):
    # history + version + deleted, without revert
    # ...
```


### Filtering history and deleted

The `history` and `deleted` endpoints support filtering by revision fields
via query parameters:

| Parameter | Example |
|-----------|---------|
| `user` | `?user=12` |
| `date_created` | `?date_created=2024-01-01T00:00:00Z` |
| `date_created__gt` | `?date_created__gt=2024-01-01T00:00:00Z` |
| `date_created__gte` | `?date_created__gte=2024-01-01T00:00:00Z` |
| `date_created__lt` | `?date_created__lt=2024-06-01T00:00:00Z` |
| `date_created__lte` | `?date_created__lte=2024-06-01T00:00:00Z` |

For example: `/my-model-url/<pk>/history/?date_created__gt=2024-01-01T00:00:00Z&user=12`


### Customizing the VersionSerializer

The `HistoryModelViewSet` comes up with actions using a `VersionSerializer`.<br>
To customize the serializer with one of your own, you can use `version_serializer`.<br>
For example, if you want to customize the `user` serializer inside a revision,
you can use the following code:

```py
from django.contrib.auth.models import User
from rest_framework import serializers
from reversion.models import Revision, Version
from reversion_rest_framework.serializers import (
    RevisionSerializer,
    VersionSerializer,
)
from reversion_rest_framework.viewsets import HistoryModelViewSet


class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ["id", "username"]


class CustomRevisionSerializer(RevisionSerializer):
    user = UserSerializer()


class CustomVersionSerializer(VersionSerializer):
    revision = CustomRevisionSerializer()


class MyModelViewSet(HistoryModelViewSet):
    version_serializer = CustomVersionSerializer
    # ...
```
