Merge branch 'master' into feat/builtin-models-types

Author: FallenDeity

.github/workflows/test.yml

@@ -68,7 +68,7 @@ jobs:
 
       # Must match `shard` definition in the test matrix:
       - name: Run pytest tests
-        run: PYTHONPATH='.' pytest --num-shards=4 --shard-id=${{ matrix.shard }} tests
+        run: PYTHONPATH='.' pytest --num-shards=4 --shard-id=${{ matrix.shard }} -n auto tests
       - name: Run mypy on the test cases
         run: mypy --strict tests/assert_type
 

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
         args: [--fix=lf]
       - id: check-case-conflict
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.9.10
+    rev: v0.11.2
     hooks:
       - id: ruff
         args: ["--fix", "--exit-non-zero-on-fix"]

CONTRIBUTING.md

@@ -68,7 +68,7 @@ You can also run pre-commit per file or for a specific path, simply replace "--a
 To execute the unit tests, simply run:
 
 ```bash
-pytest
+pytest -n auto
 ```
 
 If you get some unexpected results or want to be sure that tests run is not affected by previous one, remove `mypy` cache:

README.md

@@ -340,6 +340,60 @@ def assert_zero_count(model_type: type[models.Model]) -> None:
 ```
 
 
+### How to type a custom `models.Field`?
+
+> [!NOTE]
+> This require type generic support, see <a href="#i-cannot-use-queryset-or-manager-with-type-annotations">this section</a> to enable it.
+
+
+Django `models.Field` (and subclasses) are generic types with two parameters:
+- `_ST`: type that can be used when setting a value
+- `_GT`: type that will be returned when getting a value
+
+When you create a subclass, you have two options depending on how strict you want
+the type to be for consumers of your custom field.
+
+1. Generic subclass:
+
+```python
+from typing import TypeVar, reveal_type
+from django.db import models
+
+_ST = TypeVar("_ST", contravariant=True)
+_GT = TypeVar("_GT", covariant=True)
+
+class MyIntegerField(models.IntegerField[_ST, _GT]):
+    ...
+
+class User(models.Model):
+    my_field = MyIntegerField()
+
+
+reveal_type(User().my_field) # N: Revealed type is "int"
+User().my_field = "12"  # OK (because Django IntegerField allows str and will try to coerce it)
+```
+
+2. Non-generic subclass (more strict):
+
+```python
+from typing import reveal_type
+from django.db import models
+
+# This is a non-generic subclass being very explicit
+# that it expects only int when setting values.
+class MyStrictIntegerField(models.IntegerField[int, int]):
+    ...
+
+class User(models.Model):
+    my_field = MyStrictIntegerField()
+
+
+reveal_type(User().my_field) # N: Revealed type is "int"
+User().my_field = "12" # E: Incompatible types in assignment (expression has type "str", variable has type "int")
+```
+
+See mypy section on [generic classes subclasses](https://mypy.readthedocs.io/en/stable/generics.html#defining-subclasses-of-generic-classes).
+
 ## Related projects
 
 - [`awesome-python-typing`](https://github.com/typeddjango/awesome-python-typing) - Awesome list of all typing-related things in Python.

django-stubs/contrib/admin/decorators.pyi

@@ -13,25 +13,29 @@ _F = TypeVar("_F", bound=Callable[..., Any])
 @overload
 def action(
     function: _F,
+    *,
     permissions: Sequence[str] | None = ...,
     description: _StrOrPromise | None = ...,
 ) -> _F: ...
 @overload
 def action(
+    function: None = None,
     *,
     permissions: Sequence[str] | None = ...,
     description: _StrOrPromise | None = ...,
 ) -> Callable[[_F], _F]: ...
 @overload
 def display(
     function: _F,
+    *,
     boolean: bool | None = ...,
     ordering: str | Combinable | BaseExpression | None = ...,
     description: _StrOrPromise | None = ...,
     empty_value: str | None = ...,
 ) -> _F: ...
 @overload
 def display(
+    function: None = None,
     *,
     boolean: bool | None = ...,
     ordering: str | Combinable | BaseExpression | None = ...,

django-stubs/contrib/admin/helpers.pyi

@@ -10,6 +10,7 @@ from django.forms.boundfield import BoundField
 from django.forms.models import ModelForm
 from django.forms.utils import ErrorDict, ErrorList
 from django.forms.widgets import Media, Widget
+from django.utils.functional import cached_property
 from django.utils.safestring import SafeString
 from typing_extensions import TypedDict
 
@@ -62,6 +63,8 @@ class Fieldset:
         description: str | None = ...,
         model_admin: ModelAdmin | None = ...,
     ) -> None: ...
+    @cached_property
+    def is_collapsible(self) -> bool: ...
     @property
     def media(self) -> Media: ...
     def __iter__(self) -> Iterator[Fieldline]: ...
@@ -146,6 +149,8 @@ class InlineAdminFormSet:
     def inline_formset_data(self) -> str: ...
     @property
     def forms(self) -> list[BaseForm]: ...
+    @cached_property
+    def is_collapsible(self) -> bool: ...
     def non_form_errors(self) -> ErrorList: ...
     @property
     def media(self) -> Media: ...

django-stubs/contrib/admin/options.pyi

@@ -56,7 +56,7 @@ class IncorrectLookupParameters(Exception): ...
 FORMFIELD_FOR_DBFIELD_DEFAULTS: Any
 csrf_protect_m: Any
 
-_FieldGroups: TypeAlias = Sequence[str | Sequence[str]]
+_FieldGroups: TypeAlias = _ListOrTuple[str | _ListOrTuple[str]]
 
 @type_check_only
 class _OptionalFieldOpts(TypedDict, total=False):
@@ -67,9 +67,6 @@ class _OptionalFieldOpts(TypedDict, total=False):
 class _FieldOpts(_OptionalFieldOpts, total=True):
     fields: _FieldGroups
 
-# Workaround for mypy issue, a Sequence type should be preferred here.
-# https://github.com/python/mypy/issues/8921
-# _FieldsetSpec = Sequence[Tuple[Optional[str], _FieldOpts]]
 _FieldsetSpec: TypeAlias = _ListOrTuple[tuple[_StrOrPromise | None, _FieldOpts]]
 _ListFilterT: TypeAlias = (
     type[ListFilter]
@@ -82,7 +79,8 @@ _ListFilterT: TypeAlias = (
 # Generic type specifically for models, for use in BaseModelAdmin and subclasses
 # https://github.com/typeddjango/django-stubs/issues/482
 _ModelT = TypeVar("_ModelT", bound=Model)
-_DisplayT: TypeAlias = _ListOrTuple[str | Callable[[_ModelT], str | bool]]
+_DisplayT: TypeAlias = str | Callable[[_ModelT], str | bool]
+_ListDisplayT: TypeAlias = _ListOrTuple[_DisplayT[_ModelT]]
 
 # Options `form`, `list_display`, `list_display_links` and `actions` are not marked as `ClassVar` due to the
 # limitations of the current type system: `ClassVar` cannot contain type variables.
@@ -125,12 +123,12 @@ class BaseModelAdmin(Generic[_ModelT]):
     def get_exclude(self, request: HttpRequest, obj: _ModelT | None = ...) -> _ListOrTuple[str] | None: ...
     def get_fields(self, request: HttpRequest, obj: _ModelT | None = ...) -> _FieldGroups: ...
     def get_fieldsets(self, request: HttpRequest, obj: _ModelT | None = ...) -> _FieldsetSpec: ...
-    def get_inlines(self, request: HttpRequest, obj: _ModelT | None) -> list[type[InlineModelAdmin]]: ...
+    def get_inlines(self, request: HttpRequest, obj: _ModelT | None) -> _ListOrTuple[type[InlineModelAdmin]]: ...
     def get_ordering(self, request: HttpRequest) -> _ListOrTuple[str]: ...
     def get_readonly_fields(self, request: HttpRequest, obj: _ModelT | None = ...) -> _ListOrTuple[str]: ...
     def get_prepopulated_fields(self, request: HttpRequest, obj: _ModelT | None = ...) -> dict[str, Sequence[str]]: ...
     def get_queryset(self, request: HttpRequest) -> QuerySet[_ModelT]: ...
-    def get_sortable_by(self, request: HttpRequest) -> _DisplayT[_ModelT]: ...
+    def get_sortable_by(self, request: HttpRequest) -> _ListDisplayT[_ModelT]: ...
     @overload
     @deprecated("None value for the request parameter will be removed in Django 6.0.")
     def lookup_allowed(self, lookup: str, value: str, request: None = None) -> bool: ...
@@ -150,8 +148,8 @@ _ModelAdmin = TypeVar("_ModelAdmin", bound=ModelAdmin[Any])
 _ActionCallable: TypeAlias = Callable[[_ModelAdmin, HttpRequest, QuerySet[_ModelT]], HttpResponseBase | None]
 
 class ModelAdmin(BaseModelAdmin[_ModelT]):
-    list_display: _DisplayT[_ModelT]
-    list_display_links: _DisplayT[_ModelT] | None
+    list_display: _ListDisplayT[_ModelT]
+    list_display_links: _ListDisplayT[_ModelT] | None
     list_filter: ClassVar[_ListOrTuple[_ListFilterT]]
     list_select_related: ClassVar[bool | _ListOrTuple[str]]
     list_per_page: ClassVar[int]
@@ -220,8 +218,10 @@ class ModelAdmin(BaseModelAdmin[_ModelT]):
         self, request: HttpRequest, default_choices: list[tuple[str, str]] = ...
     ) -> list[tuple[str, str]]: ...
     def get_action(self, action: Callable | str) -> tuple[Callable[..., str], str, str] | None: ...
-    def get_list_display(self, request: HttpRequest) -> _DisplayT[_ModelT]: ...
-    def get_list_display_links(self, request: HttpRequest, list_display: _DisplayT[_ModelT]) -> _DisplayT[_ModelT]: ...
+    def get_list_display(self, request: HttpRequest) -> _ListDisplayT[_ModelT]: ...
+    def get_list_display_links(
+        self, request: HttpRequest, list_display: _ListDisplayT[_ModelT]
+    ) -> _ListDisplayT[_ModelT]: ...
     def get_list_filter(self, request: HttpRequest) -> _ListOrTuple[_ListFilterT]: ...
     def get_list_select_related(self, request: HttpRequest) -> bool | _ListOrTuple[str]: ...
     def get_search_fields(self, request: HttpRequest) -> _ListOrTuple[str]: ...

django-stubs/contrib/admin/tests.pyi

@@ -1,5 +1,5 @@
-from collections.abc import Callable, Generator
-from contextlib import contextmanager
+from collections.abc import Callable
+from contextlib import AbstractContextManager
 from typing import Any
 
 from django.contrib.staticfiles.testing import StaticLiveServerTestCase
@@ -17,8 +17,7 @@ class AdminSeleniumTestCase(SeleniumTestCase, StaticLiveServerTestCase):
     def wait_until_visible(self, css_selector: str, timeout: int = ...) -> None: ...
     def wait_until_invisible(self, css_selector: str, timeout: int = ...) -> None: ...
     def wait_page_ready(self, timeout: int = ...) -> None: ...
-    @contextmanager
-    def wait_page_loaded(self, timeout: int = ...) -> Generator[None, None, None]: ...
+    def wait_page_loaded(self, timeout: int = ...) -> AbstractContextManager[None]: ...
     def admin_login(self, username: str, password: str, login_url: str = ...) -> None: ...
     def select_option(self, selector: str, value: Any) -> None: ...
     def deselect_option(self, selector: str, value: Any) -> None: ...

django-stubs/contrib/admin/utils.pyi

@@ -5,7 +5,7 @@ from typing import Any, Literal, TypeVar, overload, type_check_only
 from uuid import UUID
 
 from _typeshed import Unused
-from django.contrib.admin.options import BaseModelAdmin
+from django.contrib.admin.options import BaseModelAdmin, _DisplayT, _FieldGroups, _FieldsetSpec, _ListDisplayT, _ModelT
 from django.contrib.admin.sites import AdminSite
 from django.db.models.base import Model
 from django.db.models.deletion import Collector
@@ -31,8 +31,11 @@ def prepare_lookup_value(
 def build_q_object_from_lookup_parameters(parameters: dict[str, list[str]]) -> Q: ...
 def quote(s: int | str | UUID) -> str: ...
 def unquote(s: str) -> str: ...
-def flatten(fields: Any) -> list[Callable | str]: ...
-def flatten_fieldsets(fieldsets: Any) -> list[Callable | str]: ...
+@overload
+def flatten(fields: _FieldGroups) -> list[str]: ...
+@overload
+def flatten(fields: _ListDisplayT[_ModelT]) -> list[_DisplayT[_ModelT]]: ...
+def flatten_fieldsets(fieldsets: _FieldsetSpec) -> list[str]: ...
 def get_deleted_objects(
     objs: Sequence[Model | None] | QuerySet[Model], request: HttpRequest, admin_site: AdminSite
 ) -> tuple[list[str], dict[str, int], set[str], list[str]]: ...

django-stubs/contrib/admin/views/main.pyi

@@ -3,7 +3,7 @@ from typing import Any, Literal
 
 from django import forms
 from django.contrib.admin.filters import ListFilter
-from django.contrib.admin.options import ModelAdmin, _DisplayT, _ListFilterT
+from django.contrib.admin.options import ModelAdmin, _ListDisplayT, _ListFilterT
 from django.db.models.base import Model
 from django.db.models.expressions import Expression
 from django.db.models.options import Options
@@ -26,8 +26,8 @@ class ChangeList:
     opts: Options
     lookup_opts: Options
     root_queryset: QuerySet
-    list_display: _DisplayT
-    list_display_links: _DisplayT
+    list_display: _ListDisplayT
+    list_display_links: _ListDisplayT
     list_filter: Sequence[_ListFilterT]
     date_hierarchy: Any
     search_fields: Sequence[str]
@@ -58,8 +58,8 @@ class ChangeList:
         self,
         request: HttpRequest,
         model: type[Model],
-        list_display: _DisplayT,
-        list_display_links: _DisplayT,
+        list_display: _ListDisplayT,
+        list_display_links: _ListDisplayT,
         list_filter: Sequence[_ListFilterT],
         date_hierarchy: str | None,
         search_fields: Sequence[str],