Integrations¶

When integrating polymorphic models into third party apps you have three primary options:

Hope it just works (it might!).
Ensure the querysets the third party apps see are not polymorphic.
Override or extend relevant third party app code to work with polymorphic querysets.

If it does not just work, option 1 is usually the easiest. We provide some integrations in polymorphic.contrib for popular third party apps and provide guidance for others below.

This page does not exhaustively cover all integrations. If you feel your integration need is very common you may consider opening a PR to either provide support in code or documentation here.

This page covers supported and tested integration advice. For all other integration advice please refer to our integrations discussion page.

For the integration examples on this page, we use the following polymorphic model hierarchy:

from django.db import models
from polymorphic.models import PolymorphicModel


class Article(PolymorphicModel):
    title = models.CharField(max_length=100)
    content = models.TextField()
    created = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.title


class BlogPost(Article):
    author = models.CharField(max_length=100)


class NewsArticle(Article):
    source = models.CharField(max_length=100)

django-guardian ¶

Added in version 1.0.2.

No special modifications are required to integrate with django-guardian. However, if you would like all object level permissions to be managed at the base model level, rather than have unique permissions for each polymorphic subclass, then you can use the helper function polymorphic.contrib.guardian.get_polymorphic_base_content_type() to unify the permissions for your entire polymorphic model tree into a single namespace a the base level:

GUARDIAN_GET_CONTENT_TYPE = \
    "polymorphic.contrib.guardian.get_polymorphic_base_content_type"

This option requires django-guardian >= 1.4.6. Details about how this option works are available in the django-guardian documentation.

django-extra-views ¶

Added in version 1.1.

The polymorphic.contrib.extra_views package provides classes to display polymorphic formsets using the classes from django-extra-views. See the documentation of:

Tip

The complete working code for this example can be found in the extra_views integration test.

Example View¶

Here’s how to create a view using PolymorphicFormSetView to handle polymorphic formsets:

from polymorphic.contrib.extra_views import PolymorphicFormSetView
from polymorphic.formsets import PolymorphicFormSetChild
from django.urls import reverse_lazy
from ..models import Article, BlogPost, NewsArticle


class ArticleFormSetView(PolymorphicFormSetView):
    model = Article
    template_name = "extra_views/article_formset.html"
    success_url = reverse_lazy("extra_views:articles")
    fields = "__all__"

    # extra will add two empty forms for models in the order of their appearance
    # in formset_children
    factory_kwargs = {"extra": 2, "can_delete": True}

    formset_children = [
        PolymorphicFormSetChild(BlogPost, fields="__all__"),
        PolymorphicFormSetChild(NewsArticle, fields="__all__"),
    ]

URL Configuration¶

Configure the URL patterns to route to your formset view:

from django.urls import path
from .views import ArticleFormSetView

app_name = "extra_views"

urlpatterns = [
    path("articles/", ArticleFormSetView.as_view(), name="articles"),
]

Template¶

The template for rendering the formset:

{% load extra_views_tags %}
<!DOCTYPE html>
<html>
<head>
    <title>Article Formset</title>
</head>
<body>
    <h1>Article Formset</h1>
    <form method="post">
        {% csrf_token %}
        {{ formset.management_form }}
        {% for form in formset %}
            <div class="formset-form">
                <h3>{{ form.instance|model_name }}</h3>
                {{ form.as_p }}
            </div>
        {% endfor %}
        <button type="submit">Save</button>
    </form>
</body>
</html>

model_name is a template tag implemented like so:

@register.filter
def model_name(instance):
    """Get the model class name of an instance."""
    return instance._meta.verbose_name.title()

django-reversion ¶

Support for django-reversion works as expected with polymorphic models. We just need to do two things:

Inherit our admin classes from both PolymorphicParentModelAdmin / PolymorphicChildModelAdmin and VersionAdmin.
Override the admin/polymorphic/object_history.html template.

Tip

The complete working code for this example can be found in the reversion integration test.

Admin Configuration¶

The admin configuration combines PolymorphicParentModelAdmin and PolymorphicChildModelAdmin with VersionAdmin:

from django.contrib import admin
from polymorphic.admin import (
    PolymorphicParentModelAdmin,
    PolymorphicChildModelAdmin,
)
from reversion.admin import VersionAdmin
from ..models import Article, BlogPost, NewsArticle


class ArticleChildAdmin(PolymorphicChildModelAdmin, VersionAdmin):
    base_model = Article


@admin.register(BlogPost)
class BlogPostAdmin(ArticleChildAdmin):
    pass


@admin.register(NewsArticle)
class NewsArticleAdmin(ArticleChildAdmin):
    pass


class ArticleParentAdmin(VersionAdmin, PolymorphicParentModelAdmin):
    """
    Parent admin for Article model with reversion support.

    Note: VersionAdmin must come before PolymorphicParentModelAdmin
    in the inheritance order.
    """

    base_model = Article
    child_models = (BlogPost, NewsArticle)
    list_display = ("title", "created")


admin.site.register(Article, ArticleParentAdmin)

Custom Template¶

Since both PolymorphicParentModelAdmin and VersionAdmin. define object_history.html template, you need to create a custom template that combines both:

{% extends 'reversion/object_history.html' %}
{% load polymorphic_admin_tags %}

{% block breadcrumbs %}
    {% breadcrumb_scope base_opts %}{{ block.super }}{% endbreadcrumb_scope %}
{% endblock %}

This makes sure both the reversion template is used, and the breadcrumb is corrected for the polymorphic model using the breadcrumb_scope tag.

model-bakery ¶

model-bakery does not work without without special configuration for polymorphic models because it overrides the polymorphic_ctype field. The best option to make it work in all cases is to supply a custom Baker class that fills in all fields except polymorphic_ctype:

yoursite/tests/baker.py¶

from polymorphic.models import PolymorphicModel
from model_bakery import baker


class PolymorphicAwareBaker(baker.Baker):
    """
    Our custom model baker ignores the polymorphic_ctype field on all polymorphic
    models - this allows the base class to set it correctly.
    See https://github.com/python/pythondotorg/issues/2567
    """

    def get_fields(self):
        fields = super().get_fields()
        if issubclass(self.model, PolymorphicModel):
            fields = {
                field
                for field in fields
                if field.name != "polymorphic_ctype"
            }
        return fields

Then in your test settings file:

BAKER_CUSTOM_CLASS = "yoursite.tests.baker.PolymorphicAwareBaker"

You may also simply pass the correct ContentType instance to the polymorphic_ctype field when creating polymorphic model instances with make()

Other Integrations¶

djangorestframework

Integrations¶

django-guardian¶

django-extra-views¶

Example View¶

URL Configuration¶

Template¶

django-reversion¶

Admin Configuration¶

Custom Template¶

model-bakery¶

Other Integrations¶

django-guardian ¶

django-extra-views ¶

django-reversion ¶

model-bakery ¶