Django Reversion

Warnings

• breaking In `v6.0.0`, the custom `pre_revision_commit` and `post_revision_commit` signals were removed. Users should now leverage Django's standard `pre_save` and `post_save` signals on the `Revision` model for similar functionality.
  Fix: Replace `reversion.signals.pre_revision_commit` or `post_revision_commit` signal connections with Django's `django.db.models.signals.pre_save` or `post_save` signals connected to the `reversion.models.Revision` model.
• breaking As of `v5.0.0`, support for Python 3.6 was dropped. The library now officially requires Python 3.9 or later, and Django 4.2 or later, as per `v6.1.0` requirements.
  Fix: Upgrade your Python environment to 3.9+ and your Django version to 4.2+ before upgrading to recent `django-reversion` versions.
• gotcha Changes to your model's schema (e.g., removing fields) can lead to `reversion.errors.RevertError: Could not load <Foo: bar> - incompatible version data` when attempting to restore older versions. This is because `django-reversion` stores versions as JSON, and schema migrations do not update this historical data.
  Fix: After significant model schema changes, it is often necessary to clear out old revision data for the affected models. Adding new fields is usually fine, but removing fields is problematic. Consider creating data migrations to handle or delete incompatible historical data.
• gotcha Bulk update operations (e.g., `QuerySet.update()`) do not trigger Django's `post_save` signals, which `django-reversion` relies on to create revisions. Consequently, changes made via bulk operations will not be recorded in version history automatically.
  Fix: To version changes from bulk operations, wrap them explicitly within a `reversion.create_revision()` context manager and manually add affected objects using `reversion.add_to_revision()` if granular control is needed, or iterate and save objects individually.
• gotcha The `reversion.RegistrationError: class 'myapp.MyModel' has already been registered with Reversion` commonly occurs due to models.py being imported twice, often caused by relative import statements in your codebase.
  Fix: Convert all relative import statements in your Django apps to absolute imports to ensure `models.py` files are not unintentionally imported multiple times.

Install

• pip install django-reversion Install with pip

Imports

• register

  from reversion import register

  Decorator for enabling version control on models.
• VersionAdmin

  from reversion.admin import VersionAdmin

  Provides version history and recovery in the Django admin interface.
• create_revision

  from reversion import create_revision

  Context manager or decorator to group changes into a single revision.
• get_for_object

  from reversion import get_for_object

  The higher-level `reversion.get_for_object` is generally preferred over direct `Version.objects` queries.

Quickstart

To get started, install `django-reversion` and add it to your `INSTALLED_APPS`. Then, register your models using the `@reversion.register()` decorator or inherit `VersionAdmin` in your `admin.py` for automatic integration. The `create_revision()` context manager or decorator is used to group multiple changes into a single historical revision, and `get_for_object()` allows programmatic access to an object's version history.

import os

# settings.py (simplified for demonstration)
INSTALLED_APPS = [
    # ... other apps
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'reversion',
    'myapp',
]

# myapp/models.py
from django.db import models
from reversion import register

@register()
class MyModel(models.Model):
    name = models.CharField(max_length=100)
    value = models.IntegerField(default=0)

    def __str__(self):
        return self.name

# myapp/admin.py
from django.contrib import admin
from reversion.admin import VersionAdmin
from .models import MyModel

@admin.register(MyModel)
class MyModelAdmin(VersionAdmin):
    pass

# Example usage in a view or management command (assuming MyModel is created)
from django.db import transaction
from reversion import create_revision, set_comment

def update_my_model(obj_id, new_name, comment):
    with create_revision():
        set_comment(comment)
        with transaction.atomic():
            obj = MyModel.objects.get(id=obj_id)
            obj.name = new_name
            obj.save()
        # Other related model saves can go here within the same revision block
        # reversion.add_to_revision(related_obj)

# To retrieve history:
from reversion import get_for_object
my_instance = MyModel.objects.first() # Get an existing instance
if my_instance:
    versions = get_for_object(my_instance).order_by('-revision__date_created')
    for version in versions:
        print(f"Version {version.pk}: {version.field_dict['name']} (Comment: {version.revision.comment}, User: {version.revision.user})")