Type Hints

Added in version 4.11.

django-polymorphic is now fully typed, and ships with type hints for all public APIs. Typing is checked with mypy and pyright in the CI pipeline.

The utility and power of the Django ORM derives from its dynamism but this makes static typing more difficult. There are no additional runtime dependencies but to use the packaged type hint classes and descriptors, you must install the following in your type checking context:

• django-stubs (required)

• django-stubs-ext (optional)

Tip

The most useful type hints to add to your own code will make it so your type checking system knows which model types your PolymorphicManager and PolymorphicQuerySet objects might return.

Correct type hints for polymorphic managers and querysets cannot be automatically inferred - you will have to add them explicitly if you want them:

Managers

You can type your managers like this. It might not always be the case that you can add hints for all child model types, especially if they are included in dependent apps. You can alleviate some of this complexity with forward type references but strict typing may not always be appropriate.

from __future__ import annotations
import typing as t
from typing_extensions import Self
from polymorphic.models import PolymorphicModel
from polymorphic.managers import PolymorphicManager


class ParentModel(PolymorphicModel):
    # fmt: off
    # If you want a polymorphic manager with type hint support you can
    # override the default one like this:
    objects: t.ClassVar[
        PolymorphicManager[
            Self | Child1 | Child2,  # union of all polymorphic types
            Self,                    # the base type (for non_polymorphic)
        ]
    ] = PolymorphicManager()
    # fmt: on


class Child1(ParentModel):
    # you may also override the type hints for the child default
    # managers to narrow the filter returns at this level
    objects: t.ClassVar[PolymorphicManager[Self | Child2, Self]]


class Child2(Child1):
    objects: t.ClassVar[PolymorphicManager[Self, Self]]

ParentModel.objects.all()  # type: PolymorphicQuerySet[ParentModel | Child1 | Child2]
ParentModel.objects.instance_of(Child1)  # type: PolymorphicQuerySet[Child1]
Child1.objects.non_polymorphic()  # type: QuerySet[Child1]

Foreign Key

django-polymorphic includes several type hint descriptors. You can use them to type your forward and reverse relationship fields. For foreign key relationships we provide PolymorphicForwardManyToOneDescriptor and PolymorphicReverseManyToOneDescriptor:

from django.db import models
from polymorphic.models import PolymorphicModel
from polymorphic.managers import (
    PolymorphicForwardManyToOneDescriptor,
    PolymorphicReverseManyToOneDescriptor,
    Nullable,  # Alias for typing.Literal[True]
)


class ParentModel(PolymorphicModel):
    related_forward = models.ForeignKey(
        "RelatedModel", on_delete=models.CASCADE, related_name="parents_reverse"
    )


class Child1(ParentModel):
    pass


class Child2(Child1):
    pass


class RelatedModel(models.Model):
    # fmt: off
    # Foreign Key Descriptor Type Hint:
    #   1. Class Attribute: ForwardManyToOneDescriptor
    #   2. Instance attribute: Union of all listed model types or None
    parent: PolymorphicForwardManyToOneDescriptor[
        ParentModel | Child1 | Child2,  # all possible polymorphic types
        ParentModel,                    # the base type (for non_polymorphic)
        Nullable,                       # when null=True
    ] = models.ForeignKey(              # type: ignore[assignment]
        ParentModel,
        on_delete=models.CASCADE,
        null=True,
    )

    # Reverse FK Relation Descriptor Type Hint:
    #   1. Class Attribute: ReverseManyToOneDescriptor
    #   2. Instance attribute: Union of all listed model types
    parents_reverse: PolymorphicReverseManyToOneDescriptor[
        ParentModel | Child1 | Child2,  # all possible polymorphic types
        ParentModel,                    # the base type (for non_polymorphic)
                                        # nullable defaults to False
    ]
    # fmt: on

RelatedModel().parent: Optional[ParentModel | Child1 | Child2]
RelatedModel().children.all(): PolymorphicQuerySet[ParentModel | Child1 | Child2]

One to One

For foreign key relationships we provide PolymorphicForwardOneToOneDescriptor and PolymorphicReverseOneToOneDescriptor:

from django.db import models
from polymorphic.models import PolymorphicModel
from polymorphic.managers import (
    PolymorphicForwardOneToOneDescriptor,
    PolymorphicReverseOneToOneDescriptor,
    Nullable,  # Alias for typing.Literal[True]
)


class ParentModel(PolymorphicModel):
    related_forward = models.OneToOneField(
        "RelatedModel", on_delete=models.CASCADE, related_name="parent_reverse"
    )


class Child1(ParentModel):
    pass


class Child2(Child1):
    pass


class RelatedModel(models.Model):
    # fmt: off
    # Forward Relation Descriptor Type Hint:
    #   1. Class Attribute: ForwardOneToOneDescriptor
    #   2. Instance attribute: Union of all listed model types or None
    parent_forward: PolymorphicForwardOneToOneDescriptor[
        ParentModel | Child1 | Child2,  # all possible polymorphic types
        ParentModel,                    # the base type (for non_polymorphic)
        Nullable,                       # when null=True
    ] = models.OneToOneField(           # type: ignore[assignment]
        "ParentModel",
        on_delete=models.CASCADE,
        null=True
    )

    # Reverse Relation Descriptor Type Hint:
    #   1. Class Attribute: ReverseOneToOneDescriptor
    #   2. Instance attribute: Union of all listed model types
    parent_reverse: PolymorphicReverseOneToOneDescriptor[
        ParentModel | Child1 | Child2,  # possible polymorphic types
        ParentModel,                    # the base type (for non_polymorphic)
                                        # nullable defaults to False
    ]
    # fmt: on

RelatedModel().parent_forward: ParentModel | Child1 | Child2 | None
RelatedModel().parent_reverse: ParentModel | Child1 | Child2

Many to Many

You can use the same PolymorphicManyToManyDescriptor for both forward and reverse ManyToManyField relationships.

The following example shows two ManyToManyField relationships:

1. PolymorphicModel -> Model (with a custom through model)

2. Model -> PolymorphicModel (with the default through model)

For the custom through model you will need to annotate using the foreign key descriptors as well.

from __future__ import annotations
from typing import ClassVar
from django.db import models
from polymorphic.models import PolymorphicModel
from polymorphic.managers import (
    PolymorphicManager,
    PolymorphicManyToManyDescriptor,
    PolymorphicForwardManyToOneDescriptor,
    PolymorphicReverseManyToOneDescriptor,
)


class ParentModel(PolymorphicModel):
    to_related = models.ManyToManyField(  # type: ignore[var-annotated]
        "RelatedModel", related_name="to_related_reverse", through="PolyThrough"
    )

    parents: PolymorphicReverseManyToOneDescriptor[
        ParentModel | Child1 | Child2, ParentModel
    ]

    objects: ClassVar[
        PolymorphicManager[ParentModel | Child1 | Child2, ParentModel]
    ]


class Child1(ParentModel):
    pass


class Child2(Child1):
    pass


class PolyThrough(PolymorphicModel):
    parent: PolymorphicForwardManyToOneDescriptor[
        ParentModel | Child1 | Child2, ParentModel
    ] = models.ForeignKey(  # type: ignore[assignment]
        ParentModel, on_delete=models.CASCADE, related_name="parents"
    )

    related = models.ForeignKey("RelatedModel", on_delete=models.CASCADE)

    objects: ClassVar[
        PolymorphicManager[PolyThrough | ThroughChild, PolyThrough]
    ]


class ThroughChild(PolyThrough):
    pass


class RelatedModel(models.Model):
    # fmt: off
    # ManyToMany Descriptor Type Hint:
    #   1. Class Attribute: ManyToManyDescriptor
    #   2. Instance attribute: PolymorphicManager for related type(s)
    to_parents: PolymorphicManyToManyDescriptor[
        ParentModel | Child1 | Child2,  # all possible polymorphic types
        ParentModel,                    # the base type (for non_polymorphic)
                                        # no custom through model
    ] = models.ManyToManyField(         # type: ignore[assignment]
        "ParentModel",
        related_name="to_parents_reverse"
    )

    # ManyToMany Descriptor for the reverse relation
    #   1. Class Attribute: ManyToManyDescriptor
    #   2. Instance attribute: PolymorphicManager for related type(s)
    to_related_reverse: PolymorphicManyToManyDescriptor[
        ParentModel | Child1 | Child2,
        ParentModel,
        PolyThrough  # custom through model (may be polymorphic!)
    ]
    # fmt: on