Skip to main content

Django model mixins and utilities

Project description

Django model mixins and utilities.


Install from PyPI with pip:

pip install django-model-utils

or get the in-development version:

pip install django-model-utils==tip

To use django-model-utils in your Django project, just import and use the utility classes described below; there is no need to modify your INSTALLED_APPS setting.


django-model-utils is tested with Django 1.2 and later on Python 2.6 and 2.7.


Please file bugs and send pull requests to the GitHub repository and issue tracker.

(Until January 2013 django-model-utils primary development was hosted at BitBucket; the issue tracker there will remain open until all issues and pull requests tracked in it are closed, but all new issues should be filed at GitHub.)


Choices provides some conveniences for setting choices on a Django model field:

from model_utils import Choices

class Article(models.Model):
    STATUS = Choices('draft', 'published')
    # ...
    status = models.CharField(choices=STATUS, default=STATUS.draft, max_length=20)

A Choices object is initialized with any number of choices. In the simplest case, each choice is a string; that string will be used both as the database representation of the choice, and the human-readable representation. Note that you can access options as attributes on the Choices object: STATUS.draft.

But you may want your human-readable versions translated, in which case you need to separate the human-readable version from the DB representation. In this case you can provide choices as two-tuples:

from model_utils import Choices

class Article(models.Model):
    STATUS = Choices(('draft', _('draft')), ('published', _('published')))
    # ...
    status = models.CharField(choices=STATUS, default=STATUS.draft, max_length=20)

But what if your database representation of choices is constrained in a way that would hinder readability of your code? For instance, you may need to use an IntegerField rather than a CharField, or you may want the database to order the values in your field in some specific way. In this case, you can provide your choices as triples, where the first element is the database representation, the second is a valid Python identifier you will use in your code as a constant, and the third is the human-readable version:

from model_utils import Choices

class Article(models.Model):
    STATUS = Choices((0, 'draft', _('draft')), (1, 'published', _('published')))
    # ...
    status = models.IntegerField(choices=STATUS, default=STATUS.draft)


A simple convenience for giving a model a set of “states.” StatusField is a CharField subclass that expects to find a STATUS class attribute on its model, and uses that as its choices. Also sets a default max_length of 100, and sets its default value to the first item in the STATUS choices:

from model_utils.fields import StatusField
from model_utils import Choices

class Article(models.Model):
    STATUS = Choices('draft', 'published')
    # ...
    status = StatusField()

(The STATUS class attribute does not have to be a Choices instance, it can be an ordinary list of two-tuples).

StatusField does not set db_index=True automatically; if you expect to frequently filter on your status field (and it will have enough selectivity to make an index worthwhile) you may want to add this yourself.


A DateTimeField subclass that monitors another field on the model, and updates itself to the current date-time whenever the monitored field changes:

from model_utils.fields import MonitorField, StatusField

class Article(models.Model):
    STATUS = Choices('draft', 'published')

    status = StatusField()
    status_changed = MonitorField(monitor='status')

(A MonitorField can monitor any type of field for changes, not only a StatusField.)


A TextField subclass that automatically pulls an excerpt out of its content (based on a “split here” marker or a default number of initial paragraphs) and stores both its content and excerpt values in the database.

A SplitField is easy to add to any model definition:

from django.db import models
from model_utils.fields import SplitField

class Article(models.Model):
    title = models.CharField(max_length=100)
    body = SplitField()

SplitField automatically creates an extra non-editable field _body_excerpt to store the excerpt. This field doesn’t need to be accessed directly; see below.

Accessing a SplitField on a model

When accessing an attribute of a model that was declared as a SplitField, a SplitText object is returned. The SplitText object has three attributes:

The full field contents.
The excerpt of content (read-only).
True if the excerpt and content are different, False otherwise.

This object also has a __unicode__ method that returns the full content, allowing SplitField attributes to appear in templates without having to access content directly.

Assuming the Article model above:

>>> a = Article.objects.all()[0]
>>> a.body.content
u'some text\n\n<!-- split -->\n\nmore text'
>>> a.body.excerpt
u'some text\n'
>>> unicode(a.body)
u'some text\n\n<!-- split -->\n\nmore text'

Assignment to a.body is equivalent to assignment to a.body.content.


a.body.excerpt is only updated when is called

Customized excerpting

By default, SplitField looks for the marker <!-- split --> alone on a line and takes everything before that marker as the excerpt. This marker can be customized by setting the SPLIT_MARKER setting.

If no marker is found in the content, the first two paragraphs (where paragraphs are blocks of text separated by a blank line) are taken to be the excerpt. This number can be customized by setting the SPLIT_DEFAULT_PARAGRAPHS setting.


An abstract base class for any model that expresses a time-range. Adds start and end nullable DateTimeFields, and a timeframed manager that returns only objects for whom the current date-time lies within their time range.


Pulls together StatusField, MonitorField and QueryManager into an abstract base class for any model with a “status.”

Just provide a STATUS class-attribute (a Choices object or a list of two-tuples), and your model will have a status field with those choices, a status_changed field containing the date-time the status was last changed, and a manager for each status that returns objects with that status only:

from model_utils.models import StatusModel
from model_utils import Choices

class Article(StatusModel):
    STATUS = Choices('draft', 'published')

# ...

a = Article()
a.status = Article.STATUS.published

# this save will update a.status_changed

# this query will only return published articles:


This manager (contributed by Jeff Elmore) should be attached to a base model class in a model-inheritance tree. It allows queries on that base model to return heterogenous results of the actual proper subtypes, without any additional queries.

For instance, if you have a Place model with subclasses Restaurant and Bar, you may want to query all Places:

nearby_places = Place.objects.filter(location='here')

But when you iterate over nearby_places, you’ll get only Place instances back, even for objects that are “really” Restaurant or Bar. If you attach an InheritanceManager to Place, you can just call the select_subclasses() method on the InheritanceManager or any QuerySet from it, and the resulting objects will be instances of Restaurant or Bar:

from model_utils.managers import InheritanceManager

class Place(models.Model):
    # ...
    objects = InheritanceManager()

class Restaurant(Place):
    # ...

class Bar(Place):
    # ...

nearby_places = Place.objects.filter(location='here').select_subclasses()
for place in nearby_places:
    # "place" will automatically be an instance of Place, Restaurant, or Bar

The database query performed will have an extra join for each subclass; if you want to reduce the number of joins and you only need particular subclasses to be returned as their actual type, you can pass subclass names to select_subclasses(), much like the built-in select_related() method:

nearby_places = Place.objects.select_subclasses("restaurant")
# restaurants will be Restaurant instances, bars will still be Place instances

InheritanceManager also provides a subclass-fetching alternative to the get() method:

place = Place.objects.get_subclass(id=some_id)
# "place" will automatically be an instance of Place, Restaurant, or Bar

If you don’t explicitly call select_subclasses() or get_subclass(), an InheritanceManager behaves identically to a normal Manager; so it’s safe to use as your default manager for the model.


Due to Django bug #16572, on Django versions prior to 1.6 InheritanceManager only supports a single level of model inheritance; it won’t work for grandchild models.


The implementation of InheritanceManager uses select_related internally. Due to Django bug #16855, this currently means that it will override any previous select_related calls on the QuerySet.


This abstract base class just provides self-updating created and modified fields on any model that inherits from it.


Many custom model managers do nothing more than return a QuerySet that is filtered in some way. QueryManager allows you to express this pattern with a minimum of boilerplate:

from django.db import models
from model_utils.managers import QueryManager

class Post(models.Model):
    published = models.BooleanField()
    pub_date = models.DateField()

    objects = models.Manager()
    public = QueryManager(published=True).order_by('-pub_date')

The kwargs passed to QueryManager will be passed as-is to the QuerySet.filter() method. You can also pass a Q object to QueryManager to express more complex conditions. Note that you can set the ordering of the QuerySet returned by the QueryManager by chaining a call to .order_by() on the QueryManager (this is not required).


A common “gotcha” when defining methods on a custom manager class is that those same methods are not automatically also available on the QuerySets returned by that manager, so are not “chainable”. This can be counterintuitive, as most of the public QuerySet API is mirrored on managers. It is possible to create a custom Manager that returns QuerySets that have the same additional methods, but this requires boilerplate code. The PassThroughManager class (contributed by Paul McLanahan) removes this boilerplate.

To use PassThroughManager, rather than defining a custom manager with additional methods, define a custom QuerySet subclass with the additional methods you want, and pass that QuerySet subclass to the PassThroughManager.for_queryset_class() class method. The returned PassThroughManager subclass will always return instances of your custom QuerySet, and you can also call methods of your custom QuerySet directly on the manager:

from datetime import datetime
from django.db import models
from django.db.models.query import QuerySet
from model_utils.managers import PassThroughManager

class PostQuerySet(QuerySet):
    def by_author(self, user):
        return self.filter(user=user)

    def published(self):
        return self.filter(

    def unpublished(self):
        return self.filter(

class Post(models.Model):
    user = models.ForeignKey(User)
    published = models.DateTimeField()

    objects = PassThroughManager.for_queryset_class(PostQuerySet)()



A ModelTracker can be added to a model to track changes in model fields. A ModelTracker allows querying for field changes since a model instance was last saved. An example of applying ModelTracker to a model:

from django.db import models
from model_utils import ModelTracker

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

    tracker = ModelTracker()

Accessing a model tracker

There are multiple methods available for checking for changes in model fields.


Returns True if the given field has changed since the last save:

>>> a = Post.objects.create(title='First Post')
>>> a.title = 'Welcome'
>>> a.tracker.has_changed('title')
>>> a.tracker.has_changed('body')

Returns True if the model instance hasn’t been saved yet.


Returns a dictionary of all fields that have been changed since the last save and the values of the fields during the last save:

>>> a = Post.objects.create(title='First Post')
>>> a.title = 'Welcome'
>>> a.body = 'First post!'
>>> a.tracker.changed()
{'title': 'First Post', 'body': ''}

Returns {} if the model instance hasn’t been saved yet.

Tracking specific fields

A fields parameter can be given to ModelTracker to limit model tracking to the specific fields:

from django.db import models
from model_utils import ModelTracker

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

    title_tracker = ModelTracker(fields=['title'])

An example using the model specified above:

>>> a = Post.objects.create(title='First Post')
>>> a.body = 'First post!'
>>> a.title_tracker.changed()


1.3.1 (2013.04.11)

  • Added explicit default to BooleanField in tests, for Django trunk compatibility.
  • Fix intermittent StatusField bug. Fixes GH-29.

1.3.0 (2013.03.27)

  • Allow specifying default value for a StatusField. Thanks Felipe Prenholato.
  • Fix calling create() on a RelatedManager that subclasses a dynamic PassThroughManager. Thanks SeiryuZ for the report. Fixes GH-24.
  • Add workaround for in InheritanceQuerySet to avoid overriding prior calls to select_related(). Thanks ivirabyan.
  • Added support for arbitrary levels of model inheritance in InheritanceManager. Thanks ivirabyan. (This feature only works in Django 1.6+ due to
  • Added ModelTracker for tracking field changes between model saves. Thanks Trey Hunner.

1.2.0 (2013.01.27)

  • Moved primary development from Bitbucket to GitHub. Bitbucket mirror will continue to receive updates; Bitbucket issue tracker will be closed once all issues tracked in it are resolved.
  • Removed deprecated ChoiceEnum, InheritanceCastModel, InheritanceCastManager, and manager_from.
  • Fixed pickling of PassThroughManager. Thanks Rinat Shigapov.
  • Set use_for_related_fields = True on QueryManager.
  • Added __len__ method to Choices. Thanks Ryan Kaskel and James Oakley.
  • Fixed InheritanceQuerySet on Django 1.5. Thanks Javier García Sogo.

1.1.0 (2012.04.13)

  • Updated AutoCreatedField, AutoLastModifiedField, MonitorField, and TimeFramedModel to use on Django 1.4. Thanks Donald Stufft.
  • Fixed annotation of InheritanceQuerysets. Thanks Jeff Elmore and Facundo Gaich.
  • Dropped support for Python 2.5 and Django 1.1. Both are no longer supported even for security fixes, and should not be used.
  • Added PassThroughManager.for_queryset_class(), which fixes use of PassThroughManager with related fields. Thanks Ryan Kaskel for report and fix.
  • Added InheritanceManager.get_subclass(). Thanks smacker.

1.0.0 (2011.06.16)

  • Fixed using SplitField on an abstract base model.
  • Fixed issue #8, adding use_for_related_fields = True to InheritanceManager.
  • Added PassThroughManager. Thanks Paul McLanahan.
  • Added pending-deprecation warnings for InheritanceCastModel, manager_from, and Django 1.1 support. Removed documentation for the deprecated utilities. Bumped ChoiceEnum from pending-deprecation to deprecation.
  • Fixed issue #6, bug with InheritanceManager and descriptor fields (e.g. FileField). Thanks zyegfryed for the fix and sayane for tests.

0.6.0 (2011.02.18)

  • updated SplitField to define get_prep_value rather than get_db_prep_value. This avoids deprecation warnings on Django trunk/1.3, but makes SplitField incompatible with Django versions prior to 1.2.
  • added InheritanceManager, a better approach to selecting subclass instances for Django 1.2+. Thanks Jeff Elmore.
  • added InheritanceCastManager and InheritanceCastQuerySet, to allow bulk casting of a queryset to child types. Thanks Gregor Müllegger.

0.5.0 (2010.09.24)

  • added manager_from (thanks George Sakkis)
  • added StatusField, MonitorField, TimeFramedModel, and StatusModel (thanks Jannis Leidel)
  • deprecated ChoiceEnum and replaced with Choices

0.4.0 (2010.03.16)

  • added SplitField
  • added ChoiceEnum
  • added South support for custom model fields


  • Added QueryManager


  • Switch to proper test skips once Django 1.3 is minimum supported.

Project details

Release history Release notifications

History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
django-model-utils-1.3.1.tar.gz (29.0 kB) Copy SHA256 hash SHA256 Source None Apr 12, 2013

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page