Update _Choices type for forms (#2565)

* Update _Choices type for forms

form.ChoiceField and other related fields accept the same input as the model's choices argument (https://docs.djangoproject.com/en/5.2/ref/forms/fields/#django.forms.ChoiceField.choices)
Ref: #2476

* Remove alias from _ChoiceInput

Author: mrgalopes

django-stubs/db/models/fields/__init__.pyi

@@ -9,14 +9,13 @@ from django import forms
 from django.core import validators  # due to weird mypy.stubtest error
 from django.core.checks import CheckMessage
 from django.db.backends.base.base import BaseDatabaseWrapper
-from django.db.models import Choices, Model
+from django.db.models import Model
 from django.db.models.expressions import Col, Combinable, Expression, Func
 from django.db.models.fields.reverse_related import ForeignObjectRel
 from django.db.models.query_utils import Q, RegisterLookupMixin
 from django.db.models.sql.compiler import SQLCompiler, _AsSqlType, _ParamsT
 from django.forms import Widget
-from django.utils.choices import BlankChoiceIterator, _Choice, _ChoiceNamedGroup, _ChoicesCallable, _ChoicesMapping
-from django.utils.choices import _Choices as _ChoicesSequence
+from django.utils.choices import BlankChoiceIterator, _Choice, _ChoiceNamedGroup, _ChoicesCallable, _ChoicesInput
 from django.utils.datastructures import DictWrapper
 from django.utils.functional import _Getter, _StrOrPromise, cached_property
 from typing_extensions import Self, TypeAlias
@@ -29,9 +28,6 @@ BLANK_CHOICE_DASH: list[tuple[str, str]]
 _ChoicesList: TypeAlias = Sequence[_Choice] | Sequence[_ChoiceNamedGroup]
 _LimitChoicesTo: TypeAlias = Q | dict[str, Any]
 _LimitChoicesToCallable: TypeAlias = Callable[[], _LimitChoicesTo]
-_Choices: TypeAlias = (
-    _ChoicesSequence | _ChoicesMapping | type[Choices] | Callable[[], _ChoicesSequence | _ChoicesMapping]
-)
 
 _F = TypeVar("_F", bound=Field, covariant=True)
 
@@ -174,7 +170,7 @@ class Field(RegisterLookupMixin, Generic[_ST, _GT]):
         unique_for_date: str | None = None,
         unique_for_month: str | None = None,
         unique_for_year: str | None = None,
-        choices: _Choices | None = None,
+        choices: _ChoicesInput | None = None,
         help_text: _StrOrPromise = "",
         db_column: str | None = None,
         db_tablespace: str | None = None,
@@ -289,7 +285,7 @@ class DecimalField(Field[_ST, _GT]):
         editable: bool = ...,
         auto_created: bool = ...,
         serialize: bool = ...,
-        choices: _Choices | None = ...,
+        choices: _ChoicesInput | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -321,7 +317,7 @@ class CharField(Field[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _Choices | None = ...,
+        choices: _ChoicesInput | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -351,7 +347,7 @@ class SlugField(CharField[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _Choices | None = ...,
+        choices: _ChoicesInput | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -387,7 +383,7 @@ class URLField(CharField[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _Choices | None = ...,
+        choices: _ChoicesInput | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -420,7 +416,7 @@ class TextField(Field[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _Choices | None = ...,
+        choices: _ChoicesInput | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -468,7 +464,7 @@ class GenericIPAddressField(Field[_ST, _GT]):
         editable: bool = ...,
         auto_created: bool = ...,
         serialize: bool = ...,
-        choices: _Choices | None = ...,
+        choices: _ChoicesInput | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -503,7 +499,7 @@ class DateField(DateTimeCheckMixin, Field[_ST, _GT]):
         editable: bool = ...,
         auto_created: bool = ...,
         serialize: bool = ...,
-        choices: _Choices | None = ...,
+        choices: _ChoicesInput | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -534,7 +530,7 @@ class TimeField(DateTimeCheckMixin, Field[_ST, _GT]):
         editable: bool = ...,
         auto_created: bool = ...,
         serialize: bool = ...,
-        choices: _Choices | None = ...,
+        choices: _ChoicesInput | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -571,7 +567,7 @@ class UUIDField(Field[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _Choices | None = ...,
+        choices: _ChoicesInput | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -608,7 +604,7 @@ class FilePathField(Field[_ST, _GT]):
         editable: bool = ...,
         auto_created: bool = ...,
         serialize: bool = ...,
-        choices: _Choices | None = ...,
+        choices: _ChoicesInput | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,

django-stubs/forms/fields.pyi

@@ -11,7 +11,7 @@ from django.db.models.fields import _ErrorMessagesDict, _ErrorMessagesMapping
 from django.forms.boundfield import BoundField
 from django.forms.forms import BaseForm
 from django.forms.widgets import Widget
-from django.utils.choices import CallableChoiceIterator, _Choices, _ChoicesCallable
+from django.utils.choices import CallableChoiceIterator, _ChoicesCallable, _ChoicesInput
 from django.utils.datastructures import _PropertyDescriptor
 from django.utils.functional import _StrOrPromise
 from typing_extensions import TypeAlias
@@ -317,14 +317,14 @@ class NullBooleanField(BooleanField):
 
 class ChoiceField(Field):
     choices: _PropertyDescriptor[
-        _Choices | _ChoicesCallable | CallableChoiceIterator,
-        _Choices | CallableChoiceIterator,
+        _ChoicesInput | _ChoicesCallable | CallableChoiceIterator,
+        _ChoicesInput | CallableChoiceIterator,
     ]
     widget: _ClassLevelWidgetT
     def __init__(
         self,
         *,
-        choices: _Choices | _ChoicesCallable = (),
+        choices: _ChoicesInput | _ChoicesCallable = (),
         required: bool = ...,
         widget: Widget | type[Widget] | None = ...,
         label: _StrOrPromise | None = ...,
@@ -355,7 +355,7 @@ class TypedChoiceField(ChoiceField):
         *,
         coerce: _CoerceCallable = ...,
         empty_value: str | None = "",
-        choices: _Choices | _ChoicesCallable = ...,
+        choices: _ChoicesInput | _ChoicesCallable = ...,
         required: bool = ...,
         widget: Widget | type[Widget] | None = ...,
         label: _StrOrPromise | None = ...,
@@ -383,7 +383,7 @@ class TypedMultipleChoiceField(MultipleChoiceField):
         *,
         coerce: _CoerceCallable = ...,
         empty_value: list[Any] | None = ...,
-        choices: _Choices | _ChoicesCallable = ...,
+        choices: _ChoicesInput | _ChoicesCallable = ...,
         required: bool = ...,
         widget: Widget | type[Widget] | None = ...,
         label: _StrOrPromise | None = ...,
@@ -459,7 +459,7 @@ class FilePathField(ChoiceField):
         recursive: bool = False,
         allow_files: bool = True,
         allow_folders: bool = False,
-        choices: _Choices | _ChoicesCallable = ...,
+        choices: _ChoicesInput | _ChoicesCallable = ...,
         required: bool = ...,
         widget: Widget | type[Widget] | None = ...,
         label: _StrOrPromise | None = ...,

django-stubs/forms/models.pyi

@@ -14,7 +14,7 @@ from django.forms.formsets import BaseFormSet
 from django.forms.renderers import BaseRenderer
 from django.forms.utils import ErrorList, _DataT, _FilesT
 from django.forms.widgets import Widget
-from django.utils.choices import BaseChoiceIterator, CallableChoiceIterator, _Choices, _ChoicesCallable
+from django.utils.choices import BaseChoiceIterator, CallableChoiceIterator, _ChoicesCallable, _ChoicesInput
 from django.utils.datastructures import _PropertyDescriptor
 from django.utils.functional import _StrOrPromise
 from typing_extensions import TypeAlias
@@ -283,8 +283,8 @@ class ModelChoiceField(ChoiceField, Generic[_M]):
     def get_limit_choices_to(self) -> _LimitChoicesTo: ...
     def label_from_instance(self, obj: _M) -> str: ...
     choices: _PropertyDescriptor[
-        _Choices | _ChoicesCallable | CallableChoiceIterator,
-        _Choices | CallableChoiceIterator | ModelChoiceIterator,
+        _ChoicesInput | _ChoicesCallable | CallableChoiceIterator,
+        _ChoicesInput | CallableChoiceIterator | ModelChoiceIterator,
     ]
     def prepare_value(self, value: Any) -> Any: ...
     def to_python(self, value: Any | None) -> _M | None: ...

django-stubs/utils/choices.pyi

@@ -1,12 +1,14 @@
-from collections.abc import Iterable, Iterator, Mapping
+from collections.abc import Callable, Iterable, Iterator, Mapping
 from typing import Any, Protocol, TypeVar, type_check_only
 
+from django.db.models import Choices
 from typing_extensions import TypeAlias
 
 _Choice: TypeAlias = tuple[Any, Any]
 _ChoiceNamedGroup: TypeAlias = tuple[str, Iterable[_Choice]]
 _Choices: TypeAlias = Iterable[_Choice | _ChoiceNamedGroup]
-_ChoicesMapping: TypeAlias = Mapping[Any, Any]  # noqa: PYI047
+_ChoicesMapping: TypeAlias = Mapping[Any, Any]
+_ChoicesInput: TypeAlias = _Choices | _ChoicesMapping | type[Choices] | Callable[[], _Choices | _ChoicesMapping]  # noqa: PYI047
 
 @type_check_only
 class _ChoicesCallable(Protocol):

tests/typecheck/forms/test_fields_choices.yml

@@ -0,0 +1,81 @@
+- case: forms_choicefield_invalid_choices
+  main: |
+    from django import forms
+
+    class MyForm(forms.Form):
+        my_choice = forms.ChoiceField(choices='test')
+  out: |
+    main:4: error: Argument "choices" to "ChoiceField" has incompatible type "str"; expected "Union[Union[Iterable[Union[Tuple[Any, Any], Tuple[str, Iterable[Tuple[Any, Any]]]]], Mapping[Any, Any], Type[Choices], Callable[[], Union[Iterable[Union[Tuple[Any, Any], Tuple[str, Iterable[Tuple[Any, Any]]]]], Mapping[Any, Any]]]], _ChoicesCallable]"  [arg-type]
+    main:4: note: "str" is missing following "_ChoicesCallable" protocol member:
+    main:4: note:     __call__
+
+- case: forms_choicefield_valid_choices
+  main: |
+    from collections.abc import Callable, Mapping, Sequence
+    from typing import TypeVar
+
+    from django import forms
+    from django.db import models
+    from typing_extensions import assert_type
+
+    _T = TypeVar("_T")
+
+
+    def to_named_seq(func: Callable[[], _T]) -> Callable[[], Sequence[tuple[str, _T]]]:
+        def inner() -> Sequence[tuple[str, _T]]:
+            return [("title", func())]
+
+        return inner
+
+
+    def to_named_mapping(func: Callable[[], _T]) -> Callable[[], Mapping[str, _T]]:
+        def inner() -> Mapping[str, _T]:
+            return {"title": func()}
+
+        return inner
+
+
+    def str_tuple() -> Sequence[tuple[str, str]]:
+        return (("foo", "bar"), ("fuzz", "bazz"))
+
+
+    def str_mapping() -> Mapping[str, str]:
+        return {"foo": "bar", "fuzz": "bazz"}
+
+
+    def int_tuple() -> Sequence[tuple[int, str]]:
+        return ((1, "bar"), (2, "bazz"))
+
+
+    def int_mapping() -> Mapping[int, str]:
+        return {3: "bar", 4: "bazz"}
+
+
+    class TestForm(forms.Form):
+        class TextChoices(models.TextChoices):
+            FIRST = "foo", "bar"
+            SECOND = "foo2", "bar"
+
+        class IntegerChoices(models.IntegerChoices):
+            FIRST = 1, "bar"
+            SECOND = 2, "bar"
+
+        char1 = forms.ChoiceField(choices=TextChoices)
+        char2 = forms.ChoiceField(choices=str_tuple)
+        char3 = forms.ChoiceField(choices=str_mapping)
+        char4 = forms.ChoiceField(choices=str_tuple())
+        char5 = forms.ChoiceField(choices=str_mapping())
+        char6 = forms.ChoiceField(choices=to_named_seq(str_tuple))
+        char7 = forms.ChoiceField(choices=to_named_mapping(str_mapping))
+        char8 = forms.ChoiceField(choices=to_named_seq(str_tuple)())
+        char9 = forms.ChoiceField(choices=to_named_mapping(str_mapping)())
+
+        int1 = forms.ChoiceField(choices=IntegerChoices)
+        int2 = forms.ChoiceField(choices=int_tuple)
+        int3 = forms.ChoiceField(choices=int_mapping)
+        int4 = forms.ChoiceField(choices=int_tuple())
+        int5 = forms.ChoiceField(choices=int_mapping())
+        int6 = forms.ChoiceField(choices=to_named_seq(int_tuple))
+        int7 = forms.ChoiceField(choices=to_named_seq(int_mapping))
+        int8 = forms.ChoiceField(choices=to_named_seq(int_tuple)())
+        int9 = forms.ChoiceField(choices=to_named_seq(int_mapping)())