Django Polymorphic

Warnings

• gotcha Query performance can degrade with many distinct subclasses. Each unique subclass in a queryset requires an additional `INNER JOIN` query to fetch its specific fields, leading to `1 + N` queries (where N is the number of distinct subclasses) for a single `all()` call. While better than `N` queries, it's a consideration for very complex hierarchies.
  Fix: Be mindful of complex inheritance hierarchies. For large querysets with many distinct subclasses, consider optimizing queries if performance bottlenecks occur. Use `iterator(chunk_size=...)` to balance memory vs. DB round trips.
• breaking The `drf-polymorphic` package was merged directly into `django-polymorphic` starting with version 4.10.0. This means import paths for `PolymorphicSerializer` and related components have changed.
  Fix: Update your import paths from `rest_polymorphic.serializers` to `polymorphic.contrib.rest_framework.serializers`.
• gotcha Methods like `values()` and `values_list()` do not return polymorphic results. They will return fields only from the base model, or specific fields if explicitly requested, but will not perform downcasting to subclasses.
  Fix: If polymorphic behavior is needed, avoid `values()` and `values_list()` and instead fetch full model instances. If you specifically need non-polymorphic behavior or a fixed set of fields, use `Model.base_objects.values(...)` which is guaranteed not to change.
• gotcha When using `dumpdata` with polymorphic models, you must include the `--natural-primary` and `--natural-foreign` flags. Polymorphic models rely on Django's `ContentType` framework, and these flags ensure correct serialization and deserialization across different database instances.
  Fix: Always use `python manage.py dumpdata --natural-primary --natural-foreign ...` for polymorphic models.
• deprecated The keyword argument `polymorphic=False` for disabling polymorphic behavior in queries is no longer supported.
  Fix: Use the `.non_polymorphic()` queryset method instead, e.g., `ModelA.objects.non_polymorphic().all()`.
• gotcha In admin integration, when defining a `PolymorphicChildModelAdmin` that might be extended by further derived classes, use `base_form` and `base_fieldsets` attributes instead of the standard `form` and `fieldsets`. This ensures that additional fields from further child models are automatically added correctly.
  Fix: Replace `form = ...` with `base_form = ...` and `fieldsets = ...` with `base_fieldsets = ...` in `PolymorphicChildModelAdmin` definitions.

Install

• pip install django-polymorphic Install latest version

Imports

• PolymorphicModel

  from polymorphic.models import PolymorphicModel

• PolymorphicParentModelAdmin

  from polymorphic.admin import PolymorphicParentModelAdmin

• PolymorphicChildModelAdmin

  from polymorphic.admin import PolymorphicChildModelAdmin

• PolymorphicManager

  from polymorphic.managers import PolymorphicManager

• PolymorphicSerializer

  from polymorphic.contrib.rest_framework.serializers import PolymorphicSerializer

  The `drf-polymorphic` package was merged into `django-polymorphic` in v4.10.0. Update import paths accordingly.

Quickstart

This quickstart demonstrates how to define polymorphic models using `PolymorphicModel` and query them. It sets up a minimal Django environment, defines a base `Project` model and two child models (`ArtProject`, `ResearchProject`), creates instances, and then queries the base model to retrieve all objects as their most specific subclass types. It also shows how to filter by `instance_of()` a specific child type. Remember to add 'polymorphic' and 'django.contrib.contenttypes' to `INSTALLED_APPS`.

import os
import django
from django.conf import settings
from django.db import models

# Minimal Django setup for runnable example
settings.configure(
    INSTALLED_APPS=[
        'django.contrib.auth',
        'django.contrib.contenttypes',
        'polymorphic',
        __name__ # For models to be registered
    ],
    DATABASES={'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}}
)
django.setup()

from polymorphic.models import PolymorphicModel

# Define your polymorphic models
class Project(PolymorphicModel):
    topic = models.CharField(max_length=90)

    def __str__(self):
        return f"{self.__class__.__name__}: {self.topic}"

class ArtProject(Project):
    artist = models.CharField(max_length=90)

    def __str__(self):
        return f"{self.__class__.__name__}: {self.topic} by {self.artist}"

class ResearchProject(Project):
    supervisor = models.CharField(max_length=90)

    def __str__(self):
        return f"{self.__class__.__name__}: {self.topic} supervised by {self.supervisor}"

# Create database schema
from django.core.management import call_command
call_command('makemigrations', __name__, interactive=False)
call_command('migrate', interactive=False)

# Create objects
Project.objects.create(topic="Department Party")
ArtProject.objects.create(topic="Painting with Tim", artist="T. Turner")
ResearchProject.objects.create(topic="Swallow Aerodynamics", supervisor="Dr. Winter")

# Query the base model to get polymorphic results
all_projects = Project.objects.all()
print("All Projects:")
for project in all_projects:
    print(project)

# Filter by subclass type
art_projects = Project.objects.instance_of(ArtProject)
print("\nArt Projects:")
for project in art_projects:
    print(project)