Remove QuerySet alias hacks via PEP 696 TypeVar defaults

The `QuerySet` class was previously named `_QuerySet` and had three aliases: `QuerySet`, `QuerySetAny` and `ValuesQuerySet`.

These hacks were mainly needed to for the ergonomic single-parameter `QuerySet[Model]`, which expanded into `_QuerySet[Model, Model]`

But now that mypy 1.10 implements PEP 696 to a fuller extent (Pyright also supports it), the 2nd type parameter can be a simple TypeVar that defaults to 1st type parameter.

Author: intgr

django-stubs/db/models/manager.pyi

@@ -7,8 +7,6 @@ from django.db.models.expressions import Combinable, OrderBy
 from django.db.models.query import QuerySet, RawQuerySet
 from typing_extensions import Self
 
-from django_stubs_ext import ValuesQuerySet
-
 _T = TypeVar("_T", bound=Model, covariant=True)
 
 class BaseManager(Generic[_T]):
@@ -107,15 +105,13 @@ class BaseManager(Generic[_T]):
         using: str | None = ...,
     ) -> RawQuerySet: ...
     # The type of values may be overridden to be more specific in the mypy plugin, depending on the fields param
-    def values(self, *fields: str | Combinable, **expressions: Any) -> ValuesQuerySet[_T, dict[str, Any]]: ...
+    def values(self, *fields: str | Combinable, **expressions: Any) -> QuerySet[_T, dict[str, Any]]: ...
     # The type of values_list may be overridden to be more specific in the mypy plugin, depending on the fields param
-    def values_list(
-        self, *fields: str | Combinable, flat: bool = ..., named: bool = ...
-    ) -> ValuesQuerySet[_T, Any]: ...
-    def dates(self, field_name: str, kind: str, order: str = ...) -> ValuesQuerySet[_T, datetime.date]: ...
+    def values_list(self, *fields: str | Combinable, flat: bool = ..., named: bool = ...) -> QuerySet[_T, Any]: ...
+    def dates(self, field_name: str, kind: str, order: str = ...) -> QuerySet[_T, datetime.date]: ...
     def datetimes(
         self, field_name: str, kind: str, order: str = ..., tzinfo: datetime.tzinfo | None = ...
-    ) -> ValuesQuerySet[_T, datetime.datetime]: ...
+    ) -> QuerySet[_T, datetime.datetime]: ...
     def none(self) -> QuerySet[_T]: ...
     def all(self) -> QuerySet[_T]: ...
     def filter(self, *args: Any, **kwargs: Any) -> QuerySet[_T]: ...

django-stubs/db/models/query.pyi

@@ -1,32 +1,33 @@
 import datetime
 from collections.abc import AsyncIterator, Collection, Iterable, Iterator, MutableMapping, Sequence, Sized
-from typing import Any, Generic, NamedTuple, TypeVar, overload
+from typing import Any, Generic, NamedTuple, overload
 
 from django.db.backends.utils import _ExecuteQuery
 from django.db.models import Manager
 from django.db.models.base import Model
 from django.db.models.expressions import Combinable, OrderBy
 from django.db.models.sql.query import Query, RawQuery
 from django.utils.functional import cached_property
-from typing_extensions import Self, TypeAlias
+from typing_extensions import Self, TypeAlias, TypeVar
 
-_T = TypeVar("_T", bound=Model, covariant=True)
-_Row = TypeVar("_Row", covariant=True)
+_T = TypeVar("_T", covariant=True)
+_Model = TypeVar("_Model", bound=Model, covariant=True)
+_Row = TypeVar("_Row", covariant=True, default=_Model)  # ONLY use together with _Model
 _QS = TypeVar("_QS", bound=_QuerySet)
 _TupleT = TypeVar("_TupleT", bound=tuple[Any, ...], covariant=True)
 
 MAX_GET_RESULTS: int
 REPR_OUTPUT_SIZE: int
 
-class BaseIterable(Generic[_Row]):
+class BaseIterable(Generic[_T]):
     queryset: QuerySet[Model]
     chunked_fetch: bool
     chunk_size: int
     def __init__(self, queryset: QuerySet[Model], chunked_fetch: bool = ..., chunk_size: int = ...) -> None: ...
-    def __aiter__(self) -> AsyncIterator[_Row]: ...
+    def __aiter__(self) -> AsyncIterator[_T]: ...
 
-class ModelIterable(Generic[_T], BaseIterable[_T]):
-    def __iter__(self) -> Iterator[_T]: ...
+class ModelIterable(Generic[_Model], BaseIterable[_Model]):
+    def __iter__(self) -> Iterator[_Model]: ...
 
 class RawModelIterable(BaseIterable[dict[str, Any]]):
     def __iter__(self) -> Iterator[dict[str, Any]]: ...
@@ -40,11 +41,11 @@ class ValuesListIterable(BaseIterable[_TupleT]):
 class NamedValuesListIterable(ValuesListIterable[NamedTuple]):
     def __iter__(self) -> Iterator[NamedTuple]: ...
 
-class FlatValuesListIterable(BaseIterable[_Row]):
-    def __iter__(self) -> Iterator[_Row]: ...
+class FlatValuesListIterable(BaseIterable[_T]):
+    def __iter__(self) -> Iterator[_T]: ...
 
-class _QuerySet(Generic[_T, _Row], Iterable[_Row], Sized):
-    model: type[_T]
+class QuerySet(Generic[_Model, _Row], Iterable[_Row], Sized):
+    model: type[_Model]
     query: Query
     _iterable_class: type[BaseIterable]
     _result_cache: list[_Row] | None
@@ -56,14 +57,14 @@ class _QuerySet(Generic[_T, _Row], Iterable[_Row], Sized):
         hints: dict[str, Model] | None = ...,
     ) -> None: ...
     @classmethod
-    def as_manager(cls) -> Manager[_T]: ...
+    def as_manager(cls) -> Manager[_Model]: ...
     def __len__(self) -> int: ...
     def __bool__(self) -> bool: ...
-    def __class_getitem__(cls: type[_QS], item: type[_T]) -> type[_QS]: ...
+    def __class_getitem__(cls: type[_QS], item: type[_Model]) -> type[_QS]: ...
     def __getstate__(self) -> dict[str, Any]: ...
     # Technically, the other QuerySet must be of the same type _T, but _T is covariant
-    def __and__(self, other: _QuerySet[_T, _Row]) -> Self: ...
-    def __or__(self, other: _QuerySet[_T, _Row]) -> Self: ...
+    def __and__(self, other: QuerySet[_Model, _Row]) -> Self: ...
+    def __or__(self, other: QuerySet[_Model, _Row]) -> Self: ...
     # IMPORTANT: When updating any of the following methods' signatures, please ALSO modify
     # the corresponding method in BaseManager.
     def iterator(self, chunk_size: int | None = ...) -> Iterator[_Row]: ...
@@ -72,44 +73,46 @@ class _QuerySet(Generic[_T, _Row], Iterable[_Row], Sized):
     async def aaggregate(self, *args: Any, **kwargs: Any) -> dict[str, Any]: ...
     def get(self, *args: Any, **kwargs: Any) -> _Row: ...
     async def aget(self, *args: Any, **kwargs: Any) -> _Row: ...
-    def create(self, **kwargs: Any) -> _T: ...
-    async def acreate(self, **kwargs: Any) -> _T: ...
+    def create(self, **kwargs: Any) -> _Model: ...
+    async def acreate(self, **kwargs: Any) -> _Model: ...
     def bulk_create(
         self,
-        objs: Iterable[_T],
+        objs: Iterable[_Model],
         batch_size: int | None = ...,
         ignore_conflicts: bool = ...,
         update_conflicts: bool = ...,
         update_fields: Collection[str] | None = ...,
         unique_fields: Collection[str] | None = ...,
-    ) -> list[_T]: ...
+    ) -> list[_Model]: ...
     async def abulk_create(
         self,
-        objs: Iterable[_T],
+        objs: Iterable[_Model],
         batch_size: int | None = ...,
         ignore_conflicts: bool = ...,
         update_conflicts: bool = ...,
         update_fields: Collection[str] | None = ...,
         unique_fields: Collection[str] | None = ...,
-    ) -> list[_T]: ...
-    def bulk_update(self, objs: Iterable[_T], fields: Iterable[str], batch_size: int | None = ...) -> int: ...
-    async def abulk_update(self, objs: Iterable[_T], fields: Iterable[str], batch_size: int | None = ...) -> int: ...
-    def get_or_create(self, defaults: MutableMapping[str, Any] | None = ..., **kwargs: Any) -> tuple[_T, bool]: ...
+    ) -> list[_Model]: ...
+    def bulk_update(self, objs: Iterable[_Model], fields: Iterable[str], batch_size: int | None = ...) -> int: ...
+    async def abulk_update(
+        self, objs: Iterable[_Model], fields: Iterable[str], batch_size: int | None = ...
+    ) -> int: ...
+    def get_or_create(self, defaults: MutableMapping[str, Any] | None = ..., **kwargs: Any) -> tuple[_Model, bool]: ...
     async def aget_or_create(
         self, defaults: MutableMapping[str, Any] | None = ..., **kwargs: Any
-    ) -> tuple[_T, bool]: ...
+    ) -> tuple[_Model, bool]: ...
     def update_or_create(
         self,
         defaults: MutableMapping[str, Any] | None = ...,
         create_defaults: MutableMapping[str, Any] | None = ...,
         **kwargs: Any,
-    ) -> tuple[_T, bool]: ...
+    ) -> tuple[_Model, bool]: ...
     async def aupdate_or_create(
         self,
         defaults: MutableMapping[str, Any] | None = ...,
         create_defaults: MutableMapping[str, Any] | None = ...,
         **kwargs: Any,
-    ) -> tuple[_T, bool]: ...
+    ) -> tuple[_Model, bool]: ...
     def earliest(self, *fields: str | OrderBy) -> _Row: ...
     async def aearliest(self, *fields: str | OrderBy) -> _Row: ...
     def latest(self, *fields: str | OrderBy) -> _Row: ...
@@ -118,8 +121,8 @@ class _QuerySet(Generic[_T, _Row], Iterable[_Row], Sized):
     async def afirst(self) -> _Row | None: ...
     def last(self) -> _Row | None: ...
     async def alast(self) -> _Row | None: ...
-    def in_bulk(self, id_list: Iterable[Any] | None = ..., *, field_name: str = ...) -> dict[Any, _T]: ...
-    async def ain_bulk(self, id_list: Iterable[Any] | None = ..., *, field_name: str = ...) -> dict[Any, _T]: ...
+    def in_bulk(self, id_list: Iterable[Any] | None = ..., *, field_name: str = ...) -> dict[Any, _Model]: ...
+    async def ain_bulk(self, id_list: Iterable[Any] | None = ..., *, field_name: str = ...) -> dict[Any, _Model]: ...
     def delete(self) -> tuple[int, dict[str, int]]: ...
     async def adelete(self) -> tuple[int, dict[str, int]]: ...
     def update(self, **kwargs: Any) -> int: ...
@@ -138,13 +141,13 @@ class _QuerySet(Generic[_T, _Row], Iterable[_Row], Sized):
         using: str | None = ...,
     ) -> RawQuerySet: ...
     # The type of values may be overridden to be more specific in the mypy plugin, depending on the fields param
-    def values(self, *fields: str | Combinable, **expressions: Any) -> _QuerySet[_T, dict[str, Any]]: ...
+    def values(self, *fields: str | Combinable, **expressions: Any) -> QuerySet[_Model, dict[str, Any]]: ...
     # The type of values_list may be overridden to be more specific in the mypy plugin, depending on the fields param
-    def values_list(self, *fields: str | Combinable, flat: bool = ..., named: bool = ...) -> _QuerySet[_T, Any]: ...
-    def dates(self, field_name: str, kind: str, order: str = ...) -> _QuerySet[_T, datetime.date]: ...
+    def values_list(self, *fields: str | Combinable, flat: bool = ..., named: bool = ...) -> QuerySet[_Model, Any]: ...
+    def dates(self, field_name: str, kind: str, order: str = ...) -> QuerySet[_Model, datetime.date]: ...
     def datetimes(
         self, field_name: str, kind: str, order: str = ..., tzinfo: datetime.tzinfo | None = ...
-    ) -> _QuerySet[_T, datetime.datetime]: ...
+    ) -> QuerySet[_Model, datetime.datetime]: ...
     def none(self) -> Self: ...
     def all(self) -> Self: ...
     def filter(self, *args: Any, **kwargs: Any) -> Self: ...
@@ -173,7 +176,7 @@ class _QuerySet(Generic[_T, _Row], Iterable[_Row], Sized):
         tables: Sequence[str] | None = ...,
         order_by: Sequence[str] | None = ...,
         select_params: Sequence[Any] | None = ...,
-    ) -> _QuerySet[Any, Any]: ...
+    ) -> QuerySet[Any, Any]: ...
     def reverse(self) -> Self: ...
     def defer(self, *fields: Any) -> Self: ...
     def only(self, *fields: Any) -> Self: ...
@@ -192,7 +195,7 @@ class _QuerySet(Generic[_T, _Row], Iterable[_Row], Sized):
     def __getitem__(self, s: slice) -> Self: ...
     def __reversed__(self) -> Iterator[_Row]: ...
 
-class RawQuerySet(Iterable[_T], Sized):
+class RawQuerySet(Iterable[_Model], Sized):
     query: RawQuery
     def __init__(
         self,
@@ -205,28 +208,28 @@ class RawQuerySet(Iterable[_T], Sized):
         hints: dict[str, Model] | None = ...,
     ) -> None: ...
     def __len__(self) -> int: ...
-    def __iter__(self) -> Iterator[_T]: ...
+    def __iter__(self) -> Iterator[_Model]: ...
     def __bool__(self) -> bool: ...
     @overload
-    def __getitem__(self, k: int) -> _T: ...
+    def __getitem__(self, k: int) -> _Model: ...
     @overload
     def __getitem__(self, k: str) -> Any: ...
     @overload
-    def __getitem__(self, k: slice) -> RawQuerySet[_T]: ...
+    def __getitem__(self, k: slice) -> RawQuerySet[_Model]: ...
     @cached_property
     def columns(self) -> list[str]: ...
     @property
     def db(self) -> str: ...
-    def iterator(self) -> Iterator[_T]: ...
+    def iterator(self) -> Iterator[_Model]: ...
     @cached_property
     def model_fields(self) -> dict[str, str]: ...
-    def prefetch_related(self, *lookups: Any) -> RawQuerySet[_T]: ...
+    def prefetch_related(self, *lookups: Any) -> RawQuerySet[_Model]: ...
     def resolve_model_init_order(self) -> tuple[list[str], list[int], list[tuple[str, int]]]: ...
-    def using(self, alias: str | None) -> RawQuerySet[_T]: ...
-
-_QuerySetAny: TypeAlias = _QuerySet  # noqa: PYI047
+    def using(self, alias: str | None) -> RawQuerySet[_Model]: ...
 
-QuerySet: TypeAlias = _QuerySet[_T, _T]
+# Obsolete aliases of QuerySet, for compatibility only.
+_QuerySet: TypeAlias = QuerySet[_T, _Row]
+_QuerySetAny: TypeAlias = QuerySet  # noqa: PYI047
 
 class Prefetch:
     prefetch_through: str
@@ -240,8 +243,8 @@ class Prefetch:
     def get_current_to_attr(self, level: int) -> tuple[str, str]: ...
     def get_current_queryset(self, level: int) -> QuerySet | None: ...
 
-def prefetch_related_objects(model_instances: Iterable[_T], *related_lookups: str | Prefetch) -> None: ...
-async def aprefetch_related_objects(model_instances: Iterable[_T], *related_lookups: str | Prefetch) -> None: ...
+def prefetch_related_objects(model_instances: Iterable[_Model], *related_lookups: str | Prefetch) -> None: ...
+async def aprefetch_related_objects(model_instances: Iterable[_Model], *related_lookups: str | Prefetch) -> None: ...
 def get_prefetcher(instance: Model, through_attr: str, to_attr: str) -> tuple[Any, Any, bool, bool]: ...
 
 class InstanceCheckMeta(type): ...

ext/django_stubs_ext/aliases.py

@@ -6,7 +6,7 @@
     from django.utils.functional import _StrPromise as StrPromise
 
     QuerySetAny = _QuerySetAny
-    ValuesQuerySet = _QuerySet[_T, _Row]
+    ValuesQuerySet = _QuerySet[_T, _Row]  # TODO think about this!
 else:
     from django.db.models.query import QuerySet
     from django.utils.functional import Promise as StrPromise

setup.py

@@ -26,7 +26,7 @@ def find_stub_files(name: str) -> List[str]:
     "django-stubs-ext>=5.0.0",
     "tomli; python_version < '3.11'",
     # Types:
-    "typing-extensions",
+    "typing-extensions>=4.11.0",
     "types-PyYAML",
 ]
 

tests/typecheck/contrib/admin/test_decorators.yml

@@ -108,7 +108,7 @@
         def method_action_invalid_fancy(self, request: HttpRequest, queryset: int) -> None: ...
 
         def method(self) -> None:
-            reveal_type(self.method_action_bare)  # N: Revealed type is "def (django.http.request.HttpRequest, django.db.models.query._QuerySet[main.MyModel, main.MyModel])"
-            reveal_type(self.method_action_fancy)  # N: Revealed type is "def (django.http.request.HttpRequest, django.db.models.query._QuerySet[main.MyModel, main.MyModel])"
-            reveal_type(self.method_action_http_response)  # N: Revealed type is "def (django.http.request.HttpRequest, django.db.models.query._QuerySet[main.MyModel, main.MyModel]) -> django.http.response.HttpResponse"
-            reveal_type(self.method_action_file_response)  # N: Revealed type is "def (django.http.request.HttpRequest, django.db.models.query._QuerySet[main.MyModel, main.MyModel]) -> django.http.response.FileResponse"
+            reveal_type(self.method_action_bare)  # N: Revealed type is "def (django.http.request.HttpRequest, django.db.models.query.QuerySet[main.MyModel, main.MyModel])"
+            reveal_type(self.method_action_fancy)  # N: Revealed type is "def (django.http.request.HttpRequest, django.db.models.query.QuerySet[main.MyModel, main.MyModel])"
+            reveal_type(self.method_action_http_response)  # N: Revealed type is "def (django.http.request.HttpRequest, django.db.models.query.QuerySet[main.MyModel, main.MyModel]) -> django.http.response.HttpResponse"
+            reveal_type(self.method_action_file_response)  # N: Revealed type is "def (django.http.request.HttpRequest, django.db.models.query.QuerySet[main.MyModel, main.MyModel]) -> django.http.response.FileResponse"

tests/typecheck/fields/test_related.yml

@@ -1058,7 +1058,7 @@
     out: |
         main:2: note: Revealed type is "Type[django.core.exceptions.ObjectDoesNotExist]"
         main:3: note: Revealed type is "django.db.models.fields.related_descriptors.ReverseOneToOneDescriptor[myapp.models.Other, myapp.models.MyModel]"
-        main:4: note: Revealed type is "django.db.models.query._QuerySet[myapp.models.MyModel, myapp.models.MyModel]"
+        main:4: note: Revealed type is "django.db.models.query.QuerySet[myapp.models.MyModel, myapp.models.MyModel]"
         main:5: note: Revealed type is "Type[django.core.exceptions.ObjectDoesNotExist]"
         main:6: note: Revealed type is "Type[django.core.exceptions.ObjectDoesNotExist]"
         main:9: note: Revealed type is "myapp.models.MyModel"

tests/typecheck/managers/querysets/test_annotate.yml

@@ -119,7 +119,7 @@
         from django.db.models.expressions import F
 
         qs = User.objects.annotate(foo=F('id'))
-        reveal_type(qs) # N: Revealed type is "django.db.models.query._QuerySet[django_stubs_ext.WithAnnotations[myapp__models__User, TypedDict({'foo': Any})], django_stubs_ext.WithAnnotations[myapp__models__User, TypedDict({'foo': Any})]]"
+        reveal_type(qs) # N: Revealed type is "django.db.models.query.QuerySet[django_stubs_ext.WithAnnotations[myapp__models__User, TypedDict({'foo': Any})], django_stubs_ext.WithAnnotations[myapp__models__User, TypedDict({'foo': Any})]]"
 
         annotated = qs.get()
         reveal_type(annotated) # N: Revealed type is "django_stubs_ext.WithAnnotations[myapp__models__User, TypedDict({'foo': Any})]"
@@ -144,7 +144,7 @@
         from django.db.models import Count
 
         qs = User.objects.annotate(Count('id'))
-        reveal_type(qs) # N: Revealed type is "django.db.models.query._QuerySet[django_stubs_ext.WithAnnotations[myapp__models__User], django_stubs_ext.WithAnnotations[myapp__models__User]]"
+        reveal_type(qs) # N: Revealed type is "django.db.models.query.QuerySet[django_stubs_ext.WithAnnotations[myapp__models__User], django_stubs_ext.WithAnnotations[myapp__models__User]]"
 
     installed_apps:
         - myapp
@@ -308,19 +308,19 @@
         # It's possible to provide more precise types than than this, but without inspecting the
         # arguments to .annotate, these are the best types we can infer.
         qs1 = Blog.objects.values('text').annotate(foo=F('id'))
-        reveal_type(qs1) # N: Revealed type is "django.db.models.query._QuerySet[django_stubs_ext.WithAnnotations[myapp__models__Blog, TypedDict({'foo': Any})], builtins.dict[builtins.str, Any]]"
+        reveal_type(qs1) # N: Revealed type is "django.db.models.query.QuerySet[django_stubs_ext.WithAnnotations[myapp__models__Blog, TypedDict({'foo': Any})], builtins.dict[builtins.str, Any]]"
         qs2 = Blog.objects.values_list('text').annotate(foo=F('id'))
-        reveal_type(qs2) # N: Revealed type is "django.db.models.query._QuerySet[django_stubs_ext.WithAnnotations[myapp__models__Blog, TypedDict({'foo': Any})], builtins.tuple[Any, ...]]"
+        reveal_type(qs2) # N: Revealed type is "django.db.models.query.QuerySet[django_stubs_ext.WithAnnotations[myapp__models__Blog, TypedDict({'foo': Any})], builtins.tuple[Any, ...]]"
         qs3 = Blog.objects.values_list('text', named=True).annotate(foo=F('id'))
         # TODO: Would be nice to infer a NamedTuple which contains the field 'text' (str) + any number of other fields.
         #  The reason it would have to appear to have any other fields is that annotate could potentially be called with
         #  arbitrary parameters such that we wouldn't know how many extra fields there might be.
         #  But it's not trivial to make such a NamedTuple, partly because since it is also an ordinary tuple, it would
         #  have to have an arbitrary length, but still have certain fields at certain indices with specific types.
         #  For now, Any :)
-        reveal_type(qs3) # N: Revealed type is "django.db.models.query._QuerySet[django_stubs_ext.WithAnnotations[myapp__models__Blog, TypedDict({'foo': Any})], Any]"
+        reveal_type(qs3) # N: Revealed type is "django.db.models.query.QuerySet[django_stubs_ext.WithAnnotations[myapp__models__Blog, TypedDict({'foo': Any})], Any]"
         qs4 = Blog.objects.values_list('text', flat=True).annotate(foo=F('id'))
-        reveal_type(qs4) # N: Revealed type is "django.db.models.query._QuerySet[django_stubs_ext.WithAnnotations[myapp__models__Blog, TypedDict({'foo': Any})], builtins.str]"
+        reveal_type(qs4) # N: Revealed type is "django.db.models.query.QuerySet[django_stubs_ext.WithAnnotations[myapp__models__Blog, TypedDict({'foo': Any})], builtins.str]"
 
 
         before_values_no_params = Blog.objects.values().annotate(foo=F('id')).get()