feat: add comprehensive type annotations

Author: huynguyengl99

.github/workflows/lint.yml

@@ -74,6 +74,7 @@ jobs:
           else
             just test-lock Django~=${{ matrix.django-version }}.0
           fi
+          just install
           just install-docs
       - name: Install Emacs
         if: ${{ github.event.inputs.debug == 'true' }}

justfile

@@ -53,9 +53,16 @@ install-playwright:
 install-docs:
     uv sync --group docs --all-extras
 
-# run static type checking
-check-types:
-    #TODO @just run mypy src/polymorphic
+# run static type checking with mypy
+check-types-mypy:
+    @just run mypy src/polymorphic
+
+# run static type checking with pyright
+check-types-pyright:
+    @just run pyright src/polymorphic
+
+# run all static type checking
+check-types: check-types-mypy check-types-pyright
 
 # run package checks
 check-package:

pyproject.toml

@@ -76,7 +76,7 @@ exclude = ["src/polymorphic/tests"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/polymorphic"]
-artifacts = ["*.mo"]
+artifacts = ["*.mo", "py.typed"]
 
 [tool.doc8]
 max-line-length = 100
@@ -145,15 +145,66 @@ relative_files = true
 [tool.coverage.report]
 show_missing = true
 
+[tool.mypy]
+python_version = "3.10"
+strict = false
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+check_untyped_defs = true
+disallow_untyped_decorators = false
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+plugins = ["mypy_django_plugin.main"]
+
+[[tool.mypy.overrides]]
+module = "polymorphic.tests.*"
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "example.*"
+ignore_errors = true
+
+[tool.django-stubs]
+django_settings_module = "polymorphic.tests.settings"
+
+[tool.pyright]
+pythonVersion = "3.10"
+typeCheckingMode = "basic"
+include = ["src/polymorphic"]
+exclude = [
+    "**/migrations",
+    "**/tests",
+    "example",
+]
+reportMissingImports = true
+reportMissingTypeStubs = false
+reportUnusedImport = true
+reportUnusedClass = false
+reportUnusedFunction = false
+reportUnusedVariable = true
+reportDuplicateImport = true
+reportOptionalMemberAccess = false
+reportGeneralTypeIssues = false
+reportOptionalSubscript = false
+reportPrivateImportUsage = false
+
 [dependency-groups]
 dev = [
     "coverage>=7.6.1",
     "dj-database-url>=2.2.0",
+    "django-stubs>=5.1.1",
     "django-test-migrations>=1.5.0",
     "ipdb>=0.13.13",
     "ipython>=8.18.1",
     "mypy>=1.14.1",
     "pre-commit>=3.5.0",
+    "pyright>=1.1.390",
     "pytest>=8.3.4",
     "pytest-cov>=5.0.0",
     "pytest-django>=4.10.0",

src/polymorphic/__init__.py

@@ -19,12 +19,14 @@
 Seamless Polymorphic Inheritance for Django Models
 """
 
-VERSION = "4.10.4"
+from typing import Final
 
-__title__ = "Django Polymorphic"
+VERSION: Final[str] = "4.10.4"
+
+__title__: Final = "Django Polymorphic"
 __version__ = VERSION  # version synonym for backwards compatibility
-__author__ = "Brian Kohan"
-__license__ = "BSD-3-Clause"
-__copyright__ = (
+__author__: Final[str] = "Brian Kohan"
+__license__: Final = "BSD-3-Clause"
+__copyright__: Final[str] = (
     "Copyright 2010-2025, Bert Constantin, Chris Glass, Diederik van der Boor, Brian Kohan"
 )

src/polymorphic/admin/childadmin.py

@@ -2,22 +2,36 @@
 The child admin displays the change/delete view of the subclass model.
 """
 
+from __future__ import annotations
+
 import inspect
+from typing import TYPE_CHECKING, Any
 
 from django.contrib import admin
+from django.db import models
+from django.forms import ModelForm
+from django.http import HttpRequest
 from django.urls import resolve
 from django.utils.translation import gettext_lazy as _
+from typing_extensions import TypeVar
 
 from polymorphic.utils import get_base_polymorphic_model
 
 from ..admin import PolymorphicParentModelAdmin
 
+_ModelT = TypeVar("_ModelT", bound=models.Model, default=models.Model)
+
+if TYPE_CHECKING:
+    _ModelAdminBase = admin.ModelAdmin[_ModelT]
+else:
+    _ModelAdminBase = admin.ModelAdmin
+
 
 class ParentAdminNotRegistered(RuntimeError):
     "The admin site for the model is not registered."
 
 
-class PolymorphicChildModelAdmin(admin.ModelAdmin):
+class PolymorphicChildModelAdmin(_ModelAdminBase):
     """
     The *optional* base class for the admin interface of derived models.
 
@@ -30,30 +44,32 @@ class PolymorphicChildModelAdmin(admin.ModelAdmin):
     """
 
     #: The base model that the class uses (auto-detected if not set explicitly)
-    base_model = None
+    base_model: type[models.Model] | None = None
 
     #: By setting ``base_form`` instead of ``form``, any subclass fields are automatically added to the form.
     #: This is useful when your model admin class is inherited by others.
-    base_form = None
+    base_form: type[ModelForm[Any]] | None = None
 
     #: By setting ``base_fieldsets`` instead of ``fieldsets``,
     #: any subclass fields can be automatically added.
     #: This is useful when your model admin class is inherited by others.
-    base_fieldsets = None
+    base_fieldsets: Any = None
 
     #: Default title for extra fieldset
     extra_fieldset_title = _("Contents")
 
     #: Whether the child admin model should be visible in the admin index page.
     show_in_index = False
 
-    def __init__(self, model, admin_site, *args, **kwargs):
+    def __init__(self, model: type[_ModelT], admin_site: Any, *args: Any, **kwargs: Any) -> None:
         super().__init__(model, admin_site, *args, **kwargs)
 
         if self.base_model is None:
             self.base_model = get_base_polymorphic_model(model)
 
-    def get_form(self, request, obj=None, **kwargs):
+    def get_form(
+        self, request: HttpRequest, obj: Any | None = None, change: bool = False, **kwargs: Any
+    ) -> type[ModelForm[Any]]:
         # The django admin validation requires the form to have a 'class Meta: model = ..'
         # attribute, or it will complain that the fields are missing.
         # However, this enforces all derived ModelAdmin classes to redefine the model as well,
@@ -77,7 +93,7 @@ def get_model_perms(self, request):
         return super().get_model_perms(request)
 
     @property
-    def change_form_template(self):
+    def change_form_template(self) -> list[str]:  # type: ignore[override]
         opts = self.model._meta
         app_label = opts.app_label
 
@@ -96,7 +112,7 @@ def change_form_template(self):
         ]
 
     @property
-    def delete_confirmation_template(self):
+    def delete_confirmation_template(self) -> list[str]:  # type: ignore[override]
         opts = self.model._meta
         app_label = opts.app_label
 
@@ -115,7 +131,7 @@ def delete_confirmation_template(self):
         ]
 
     @property
-    def object_history_template(self):
+    def object_history_template(self) -> list[str]:  # type: ignore[override]
         opts = self.model._meta
         app_label = opts.app_label
 

src/polymorphic/admin/filters.py

@@ -1,5 +1,12 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
 from django.contrib import admin
 from django.core.exceptions import PermissionDenied
+from django.db.models import QuerySet
+from django.http import HttpRequest
 from django.utils.translation import gettext_lazy as _
 
 
@@ -15,13 +22,15 @@ class PolymorphicChildModelFilter(admin.SimpleListFilter):
         list_filter = (PolymorphicChildModelFilter,)
     """
 
-    title = _("Type")
-    parameter_name = "polymorphic_ctype"
+    title: str = _("Type")  # type: ignore[assignment]
+    parameter_name: str = "polymorphic_ctype"
 
-    def lookups(self, request, model_admin):
+    def lookups(
+        self, request: HttpRequest, model_admin: admin.ModelAdmin[Any]
+    ) -> Iterable[tuple[str, str]]:
         return model_admin.get_child_type_choices(request, "change")
 
-    def queryset(self, request, queryset):
+    def queryset(self, request: HttpRequest, queryset: QuerySet[Any]) -> QuerySet[Any]:
         try:
             value = int(self.value())
         except TypeError:

src/polymorphic/admin/forms.py

@@ -1,3 +1,5 @@
+from typing import Any
+
 from django import forms
 from django.contrib.admin.widgets import AdminRadioSelect
 from django.utils.translation import gettext_lazy as _
@@ -15,7 +17,7 @@ class PolymorphicModelChoiceForm(forms.Form):
         label=type_label, widget=AdminRadioSelect(attrs={"class": "radiolist"})
     )
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         # Allow to easily redefine the label (a commonly expected usecase)
         super().__init__(*args, **kwargs)
         self.fields["ct_id"].label = self.type_label

src/polymorphic/admin/generic.py

@@ -1,5 +1,8 @@
+from typing import Any
+
 from django.contrib.contenttypes.admin import GenericInlineModelAdmin
 from django.contrib.contenttypes.models import ContentType
+from django.http import HttpRequest
 from django.utils.functional import cached_property
 
 from polymorphic.formsets import (
@@ -17,9 +20,11 @@ class GenericPolymorphicInlineModelAdmin(PolymorphicInlineModelAdmin, GenericInl
     """
 
     #: The formset class
-    formset = BaseGenericPolymorphicInlineFormSet
+    formset: type[BaseGenericPolymorphicInlineFormSet] = BaseGenericPolymorphicInlineFormSet  # type: ignore[assignment]
 
-    def get_formset(self, request, obj=None, **kwargs):
+    def get_formset(
+        self, request: HttpRequest, obj: Any = None, **kwargs: Any
+    ) -> type[BaseGenericPolymorphicInlineFormSet]:  # type: ignore[override]
         """
         Construct the generic inline formset class.
         """
@@ -39,19 +44,21 @@ class Child(PolymorphicInlineModelAdmin.Child):
         """
 
         # Make sure that the GFK fields are excluded from the child forms
-        formset_child = GenericPolymorphicFormSetChild
-        ct_field = "content_type"
-        ct_fk_field = "object_id"
+        formset_child: type[GenericPolymorphicFormSetChild] = GenericPolymorphicFormSetChild  # type: ignore[assignment]
+        ct_field: str = "content_type"
+        ct_fk_field: str = "object_id"
 
         @cached_property
-        def content_type(self):
+        def content_type(self) -> ContentType:
             """
             Expose the ContentType that the child relates to.
             This can be used for the ``polymorphic_ctype`` field.
             """
             return ContentType.objects.get_for_model(self.model, for_concrete_model=False)
 
-        def get_formset_child(self, request, obj=None, **kwargs):
+        def get_formset_child(
+            self, request: HttpRequest, obj: Any = None, **kwargs: Any
+        ) -> GenericPolymorphicFormSetChild:  # type: ignore[override]
             # Similar to GenericInlineModelAdmin.get_formset(),
             # make sure the GFK is automatically excluded from the form
             defaults = {"ct_field": self.ct_field, "fk_field": self.ct_fk_field}
@@ -67,4 +74,4 @@ class GenericStackedPolymorphicInline(GenericPolymorphicInlineModelAdmin):
     """
 
     #: The default template to use.
-    template = "admin/polymorphic/edit_inline/stacked.html"
+    template: str = "admin/polymorphic/edit_inline/stacked.html"