Django Model Utils

5.0.0 · active · verified Thu Apr 09

Django Model Utils is a comprehensive Python library that provides a collection of abstract base classes, managers, fields, and utilities designed to simplify common Django model patterns. It includes features like `StatusField` for managing object states, `TimeStampedModel` for automatic creation/modification timestamps, `SoftDeletableModel` for logical deletion, and `FieldTracker` for monitoring field changes. The current version is 5.0.0, and it generally keeps pace with Django's major release cycle for compatibility.

Warnings

breaking The `SaveSignalHandlingModel` has been removed. If you used this abstract base class to temporarily disable signals during a save operation, you will need to refactor your code. This model was removed in version 4.4.0 due to maintainability concerns with its modified `Model.save_base()` method.
Fix: Consider using Django's built-in `bulk_create` or `update` methods which bypass signals, or implement custom signal dispatching logic. For more complex scenarios, you might need to temporarily disconnect signals before saving and reconnect them afterwards.
breaking The `JoinQueryset.get_quoted_query()` method was removed in version 4.5.1. If your code directly invoked this method, it will now fail.
Fix: Update your code to no longer rely on `get_quoted_query()`. If you were using `JoinManager` or `JoinManagerMixin`, these were deprecated in 5.0.0; migrate to `JoinQueryset.as_manager()` instead.
breaking Version 4.0.0 dropped support for Python 2.7 and Django 1.11. Additionally, it removed internal usage of the `six` compatibility library.
Fix: Ensure your project runs on Python 3.x (specifically `>=3.8` for `django-model-utils` 5.0.0) and uses Django 2.2 or later (preferably >=3.2 as per 4.3.1 requirements).
breaking Behavioral changes to `FieldTracker` in version 4.1.0 mean it now correctly marks fields as not changed after `refresh_from_db` and respects `update_fields` when saving. It also resets states after `pre_save()` signals instead of `save()` signals.
Fix: Review existing code using `FieldTracker` within custom `save()` methods, signal handlers, or after `refresh_from_db()` to ensure the new behavior aligns with expectations. Specifically, logic relying on `tracker.changed()` within `post_save` might need adjustment if it expects changes that occurred during `pre_save` to be re-evaluated.
deprecated The `ModelTracker` was deprecated in favor of `FieldTracker` due to serious flaws in handling `ForeignKey` fields, leading to potentially many extra database queries.
Fix: Replace all instances of `ModelTracker` with `FieldTracker` to avoid performance issues and leverage improved `ForeignKey` handling.
deprecated For `SoftDeletableModel`, relying on the default `objects` manager to filter out not-deleted instances is deprecated. The `objects` manager will include deleted objects in a future release.
Fix: Always use the `available_objects` manager to retrieve only non-deleted instances, or `all_objects` when you explicitly want to include deleted instances.
gotcha In version 5.0.0, the `MonitorField` now defaults to `None` when nullable and no default is provided, instead of `django.utils.timezone.now`.
Fix: If your `MonitorField` relies on `django.utils.timezone.now` for nullable fields without an explicit default, you must now set `default=django.utils.timezone.now` explicitly to maintain the previous behavior.

Install

pip install django-model-utils Install stable version

Imports

FieldTracker
```
from model_utils import FieldTracker
```
Used for tracking changes to model fields.
StatusField
```
from model_utils.fields import StatusField
```
A CharField subclass for models with predefined states.
TimeStampedModel
```
from model_utils.models import TimeStampedModel
```
Abstract base class providing 'created' and 'modified' DateTimeFields.
SoftDeletableModel
```
from model_utils.models import SoftDeletableModel
```
Abstract base class for models with logical deletion instead of actual removal.
Choices
```
from model_utils import Choices
```
Utility for defining model field choices with conveniences.

Quickstart

This quickstart demonstrates how to use `FieldTracker` to monitor changes in a model's fields. The `tracker` instance on the model allows you to check if a specific field has changed (`has_changed()`), retrieve its previous value (`previous()`), or get a dictionary of all changed fields and their old values (`changed()`). The example shows how to integrate this logic within a custom `save` method.

from django.db import models
from model_utils import FieldTracker

class Post(models.Model):
    title = models.CharField(max_length=100)
    body = models.TextField()
    tracker = FieldTracker()

    def save(self, *args, **kwargs):
        # Example of using FieldTracker in a save method
        super().save(*args, **kwargs)
        if self.tracker.has_changed('title'):
            print(f"Title changed from '{self.tracker.previous('title')}' to '{self.title}'")

# Example usage (requires Django setup and database interaction)
# post = Post.objects.create(title='Initial Title', body='Some body content')
# post.title = 'Updated Title'
# post.save()
# print(post.tracker.changed()) # Shows all changed fields and their previous values

view raw JSON →