Welcome to django-dirtyfields’s documentation!

django-dirtyfields is a small library for tracking dirty fields on a Django model instance. Dirty means that a field’s in-memory value is different to the value in the database.

Table of Contents:

• Quickstart
• Advanced Usage
  • Verbose mode
  • Checking foreign key fields.
  • Saving dirty fields.
  • Performance Impact
  • Database Transactions Limitations
• Customisation
  • Checking many-to-many fields.
  • Checking a limited set of model fields.
  • Custom comparison function
  • Custom value normalisation function
• Contributing
• Credits

Quickstart

Install

$ pip install django-dirtyfields

Usage

To use django-dirtyfields, you need to:

• Inherit from DirtyFieldsMixin in the Django model you want to track.

from django.db import models
from dirtyfields import DirtyFieldsMixin

class ExampleModel(DirtyFieldsMixin, models.Model):
    """A simple example model to test dirty fields mixin with"""
    boolean = models.BooleanField(default=True)
    characters = models.CharField(blank=True, max_length=80)

• Use one of these 2 functions on a model instance to know if this instance is dirty, and get the dirty fields:

  • is_dirty()

  • get_dirty_fields()

Example

>>> model = ExampleModel.objects.create(boolean=True,
                                        characters="first value")
>>> model.is_dirty()
False
>>> model.get_dirty_fields()
{}

>>> model.boolean = False
>>> model.characters = "second value"

>>> model.is_dirty()
True
>>> model.get_dirty_fields()
{'boolean': True, "characters": "first_value"}

Why would you want this?

When using django.db.models.signals (django.db.models.signals.pre_save especially), it is useful to be able to see what fields have changed or not. A signal could change its behaviour depending on whether a specific field has changed, whereas otherwise, you only could work on the event that the model’s save() method had been called.