Django Modelcluster

6.4.1 · active · verified Thu Apr 09

django-modelcluster is a Django extension that allows working with 'clusters' of related models as a single unit, independently of the database. It introduces `ParentalKey` and `ClusterableModel` to enable in-memory manipulation of related objects, which is particularly useful for features like previews and revisions in content management systems like Wagtail. The current version is 6.4.1, and it maintains a consistent release schedule, often aligning with Django and Python version support.

Warnings

breaking In `ClusterForm` (v6.0 and later), child formsets are no longer built by default if neither `formsets` nor `exclude_formsets` is specified in the Meta class. This changes previous behavior where all child relations would automatically get a formset.
Fix: Explicitly define `formsets` or `exclude_formsets` within the `Meta` class of your `ClusterForm` to control which child relations have formsets.
breaking `django-modelcluster` frequently drops support for older Django and Python versions. For example, v6.4 removed Django 3.2 and Python 3.8 support.
Fix: Always check the release notes (`CHANGELOG.txt`) for version compatibility and ensure your `django-modelcluster` version aligns with your Django and Python environment.
gotcha A `ParentalKey` field must point to a model that inherits from `ClusterableModel`. Failing to do so will result in a Django system check error.
Fix: Ensure the model referenced by `ParentalKey` (e.g., the 'Band' in `ParentalKey('Band', ...)`) inherits `modelcluster.models.ClusterableModel`.
gotcha Using `related_name='+'` is not allowed on `ParentalKey` fields, as `ParentalKey` requires an accessor name for its internal mechanisms.
Fix: Provide a meaningful `related_name` for all `ParentalKey` fields, or omit it to let Django infer one.
gotcha While `django-modelcluster` provides a `QuerySet`-like API for in-memory child objects, it's a 'fake' QuerySet with limitations. Advanced queryset operations (e.g., complex `order_by` traversals, `distinct()` before v6.3, or raw SQL queries) may not work as expected or are not supported on unsaved instances, particularly in contexts like content previews.
Fix: Be aware of these limitations when querying in-memory relations. For complex logic, ensure the parent model and its children are saved, or adapt your code to work with lists/iterators where full queryset functionality isn't available.
gotcha For `ParentalManyToManyField`, only the *relationships* between the parent and the related objects are managed in memory. The *related objects themselves* (e.g., `Actor` instances in a `Movie.actors = ParentalManyToManyField(Actor)`) must already exist in the database before they can be associated in memory with the parent.
Fix: Ensure that any objects intended to be related via `ParentalManyToManyField` are persisted to the database before attempting to establish the in-memory relationship with the parent `ClusterableModel`.

Install

pip install django-modelcluster Install stable version

Imports

ClusterableModel

from modelcluster.models import ClusterableModel

ParentalKey
```
from modelcluster.fields import ParentalKey
```
ParentalKey is a specialized ForeignKey for in-memory child objects, enabling 'clustering'.

ParentalManyToManyField

from modelcluster.fields import ParentalManyToManyField

ClusterForm
```
from modelcluster.forms import ClusterForm
```
Used for handling forms with clustered models, particularly in Django's admin or Wagtail.

Quickstart

This example demonstrates defining a `ClusterableModel` (Band) and a related model (`BandMember`) connected via `ParentalKey`. It shows how to create a cluster of related objects in memory and access them before saving them to the database.

from django.db import models
from modelcluster.models import ClusterableModel
from modelcluster.fields import ParentalKey

class Band(ClusterableModel):
    name = models.CharField(max_length=255)

    def __str__(self):
        return self.name

class BandMember(models.Model):
    band = ParentalKey(
        'Band', 
        related_name='members',
        on_delete=models.CASCADE
    )
    name = models.CharField(max_length=255)

    def __str__(self):
        return self.name

# Example usage (in a Django shell or view):
beatles = Band(name='The Beatles')
# Related objects can be assigned to the in-memory 'members' attribute
beatles.members = [
    BandMember(name='John Lennon'),
    BandMember(name='Paul McCartney'),
    BandMember(name='George Harrison'),
    BandMember(name='Ringo Starr'),
]

# Accessing in-memory members (behaves like a QuerySet subset)
print([member.name for member in beatles.members.all()])
# Output: ['John Lennon', 'Paul McCartney', 'George Harrison', 'Ringo Starr']

# To save the cluster and its members to the database:
# beatles.save()
# This would also save all associated BandMember instances via ParentalKey

view raw JSON →