feat: Add QuerySetT type parameter to InheritanceManagerMixin

Add support for custom QuerySet types in InheritanceManagerMixin by
introducing a second type parameter QuerySetT with a default value.
This enables subclasses to specify their own QuerySet type while
maintaining full backwards compatibility with existing code.

Changes:
- Add QuerySetT TypeVar with default=InheritanceQuerySet[ModelT]
- Update InheritanceManagerMixin to be Generic[ModelT, QuerySetT]
- Update all return types in InheritanceManagerMixin to use QuerySetT
- Add typing_extensions dependency for Python < 3.13
- Add docstring with usage examples

Backwards compatibility:
- Existing InheritanceManager[MyModel] code works unchanged
- QuerySetT defaults to InheritanceQuerySet[ModelT] when not specified

Usage example:
    class MyQuerySet(InheritanceQuerySetMixin[MyModel], QuerySet[MyModel]):
        def custom_filter(self) -> Self:
            return self.filter(active=True)

    class MyManager(InheritanceManager[MyModel, MyQuerySet]):
        _queryset_class = MyQuerySet

Author: lee3jjang

model_utils/managers.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
+import sys
 import warnings
-from typing import TYPE_CHECKING, Any, Generic, Sequence, TypeVar, cast, overload
+from typing import TYPE_CHECKING, Any, Generic, Sequence, cast, overload
 
 from django.core.exceptions import ObjectDoesNotExist
 from django.db import connection, models
@@ -10,8 +11,21 @@
 from django.db.models.query import ModelIterable, QuerySet
 from django.db.models.sql.datastructures import Join
 
+if sys.version_info >= (3, 13):
+    from typing import TypeVar
+else:
+    from typing_extensions import TypeVar
+
 ModelT = TypeVar('ModelT', bound=models.Model, covariant=True)
 
+# TypeVar for QuerySet with default (enables backwards compatibility)
+# When only ModelT is specified, QuerySetT defaults to InheritanceQuerySet[ModelT]
+QuerySetT = TypeVar(
+    'QuerySetT',
+    bound='InheritanceQuerySet[Any]',
+    default='InheritanceQuerySet[ModelT]',
+)
+
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
@@ -226,57 +240,82 @@ def instance_of(self, *models: type[ModelT]) -> InheritanceQuerySet[ModelT]:
         )
 
 
-class InheritanceManagerMixin(Generic[ModelT]):
-    _queryset_class = InheritanceQuerySet
+class InheritanceManagerMixin(Generic[ModelT, QuerySetT]):
+    """
+    Mixin for Manager classes that provides inheritance-aware queryset methods.
+
+    This mixin supports an optional second type parameter ``QuerySetT`` which
+    defaults to ``InheritanceQuerySet[ModelT]``. This allows subclasses to
+    specify a custom QuerySet type while maintaining backwards compatibility
+    with existing code that only specifies the model type.
+
+    Example usage with default QuerySet::
+
+        class MyManager(InheritanceManager[MyModel]):
+            pass  # get_queryset() returns InheritanceQuerySet[MyModel]
+
+    Example usage with custom QuerySet::
+
+        class MyQuerySet(InheritanceQuerySetMixin[MyModel], QuerySet[MyModel]):
+            def custom_filter(self) -> Self:
+                return self.filter(active=True)
+
+        class MyManager(InheritanceManager[MyModel, MyQuerySet]):
+            _queryset_class = MyQuerySet
+
+            def get_queryset(self) -> MyQuerySet:
+                return MyQuerySet(self.model, using=self._db)
+    """
+    _queryset_class: type[QuerySetT] = InheritanceQuerySet  # type: ignore[assignment]
 
     if TYPE_CHECKING:
         from collections.abc import Sequence
 
-        def none(self) -> InheritanceQuerySet[ModelT]:
+        def none(self) -> QuerySetT:
             ...
 
-        def all(self) -> InheritanceQuerySet[ModelT]:
+        def all(self) -> QuerySetT:
             ...
 
-        def filter(self, *args: Any, **kwargs: Any) -> InheritanceQuerySet[ModelT]:
+        def filter(self, *args: Any, **kwargs: Any) -> QuerySetT:
             ...
 
-        def exclude(self, *args: Any, **kwargs: Any) -> InheritanceQuerySet[ModelT]:
+        def exclude(self, *args: Any, **kwargs: Any) -> QuerySetT:
             ...
 
-        def complex_filter(self, filter_obj: Any) -> InheritanceQuerySet[ModelT]:
+        def complex_filter(self, filter_obj: Any) -> QuerySetT:
             ...
 
-        def union(self, *other_qs: Any, all: bool = ...) -> InheritanceQuerySet[ModelT]:
+        def union(self, *other_qs: Any, all: bool = ...) -> QuerySetT:
             ...
 
-        def intersection(self, *other_qs: Any) -> InheritanceQuerySet[ModelT]:
+        def intersection(self, *other_qs: Any) -> QuerySetT:
             ...
 
-        def difference(self, *other_qs: Any) -> InheritanceQuerySet[ModelT]:
+        def difference(self, *other_qs: Any) -> QuerySetT:
             ...
 
         def select_for_update(
             self, nowait: bool = ..., skip_locked: bool = ..., of: Sequence[str] = ..., no_key: bool = ...
-        ) -> InheritanceQuerySet[ModelT]:
+        ) -> QuerySetT:
             ...
 
-        def select_related(self, *fields: Any) -> InheritanceQuerySet[ModelT]:
+        def select_related(self, *fields: Any) -> QuerySetT:
             ...
 
-        def prefetch_related(self, *lookups: Any) -> InheritanceQuerySet[ModelT]:
+        def prefetch_related(self, *lookups: Any) -> QuerySetT:
             ...
 
-        def annotate(self, *args: Any, **kwargs: Any) -> InheritanceQuerySet[ModelT]:
+        def annotate(self, *args: Any, **kwargs: Any) -> QuerySetT:
             ...
 
-        def alias(self, *args: Any, **kwargs: Any) -> InheritanceQuerySet[ModelT]:
+        def alias(self, *args: Any, **kwargs: Any) -> QuerySetT:
             ...
 
-        def order_by(self, *field_names: Any) -> InheritanceQuerySet[ModelT]:
+        def order_by(self, *field_names: Any) -> QuerySetT:
             ...
 
-        def distinct(self, *field_names: Any) -> InheritanceQuerySet[ModelT]:
+        def distinct(self, *field_names: Any) -> QuerySetT:
             ...
 
         def extra(
@@ -287,38 +326,38 @@ def extra(
             tables: list[str] | None = ...,
             order_by: Sequence[str] | None = ...,
             select_params: Sequence[Any] | None = ...,
-        ) -> InheritanceQuerySet[Any]:
+        ) -> QuerySetT:
             ...
 
-        def reverse(self) -> InheritanceQuerySet[ModelT]:
+        def reverse(self) -> QuerySetT:
             ...
 
-        def defer(self, *fields: Any) -> InheritanceQuerySet[ModelT]:
+        def defer(self, *fields: Any) -> QuerySetT:
             ...
 
-        def only(self, *fields: Any) -> InheritanceQuerySet[ModelT]:
+        def only(self, *fields: Any) -> QuerySetT:
             ...
 
-        def using(self, alias: str | None) -> InheritanceQuerySet[ModelT]:
+        def using(self, alias: str | None) -> QuerySetT:
             ...
 
-    def get_queryset(self) -> InheritanceQuerySet[ModelT]:
+    def get_queryset(self) -> QuerySetT:
         model: type[ModelT] = self.model  # type: ignore[attr-defined]
         return self._queryset_class(model)
 
     def select_subclasses(
         self, *subclasses: str | type[models.Model]
-    ) -> InheritanceQuerySet[ModelT]:
-        return self.get_queryset().select_subclasses(*subclasses)
+    ) -> QuerySetT:
+        return self.get_queryset().select_subclasses(*subclasses)  # type: ignore[return-value]
 
     def get_subclass(self, *args: object, **kwargs: object) -> ModelT:
         return self.get_queryset().get_subclass(*args, **kwargs)
 
-    def instance_of(self, *models: type[ModelT]) -> InheritanceQuerySet[ModelT]:
-        return self.get_queryset().instance_of(*models)
+    def instance_of(self, *models: type[ModelT]) -> QuerySetT:
+        return self.get_queryset().instance_of(*models)  # type: ignore[return-value]
 
 
-class InheritanceManager(InheritanceManagerMixin[ModelT], models.Manager[ModelT]):
+class InheritanceManager(InheritanceManagerMixin[ModelT, QuerySetT], models.Manager[ModelT]):
     pass
 
 

setup.py

@@ -30,7 +30,10 @@ def long_desc(root_path):
     url='https://github.com/jazzband/django-model-utils',
     packages=find_packages(exclude=['tests*']),
     python_requires=">=3.10",
-    install_requires=['Django>=4.2'],
+    install_requires=[
+        'Django>=4.2',
+        'typing_extensions>=4.0.0; python_version < "3.13"',
+    ],
     classifiers=[
         'Development Status :: 5 - Production/Stable',
         'Environment :: Web Environment',