5.0: Add django.utils.choices (typeddjango#2075)

* 5.0: Add `django.utils.choices`

* 5.0: Fix type errors

Author: sudosubin

django-stubs/contrib/admin/widgets.pyi

@@ -4,10 +4,10 @@ from typing import Any
 from django import forms
 from django.contrib.admin.sites import AdminSite
 from django.core.files.base import File
-from django.db.models.fields import _FieldChoices
 from django.db.models.fields.reverse_related import ManyToManyRel, ManyToOneRel
 from django.forms.models import ModelChoiceIterator
 from django.forms.widgets import _OptAttrs
+from django.utils.choices import _Choices
 from django.utils.functional import _StrOrPromise
 
 class FilteredSelectMultiple(forms.SelectMultiple):
@@ -18,7 +18,7 @@ class FilteredSelectMultiple(forms.SelectMultiple):
         verbose_name: _StrOrPromise,
         is_stacked: bool,
         attrs: _OptAttrs | None = ...,
-        choices: _FieldChoices = ...,
+        choices: _Choices = ...,
     ) -> None: ...
 
 class AdminDateWidget(forms.DateInput):

django-stubs/contrib/gis/db/models/fields.pyi

@@ -14,7 +14,8 @@ from django.contrib.gis.geos import (
 )
 from django.core.validators import _ValidatorCallable
 from django.db.models.expressions import Combinable, Expression
-from django.db.models.fields import NOT_PROVIDED, Field, _ErrorMessagesMapping, _FieldChoices
+from django.db.models.fields import NOT_PROVIDED, Field, _ErrorMessagesMapping
+from django.utils.choices import _Choices
 from django.utils.functional import _StrOrPromise
 
 # __set__ value type
@@ -58,7 +59,7 @@ class BaseSpatialField(Field[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -104,7 +105,7 @@ class GeometryField(BaseSpatialField[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,

django-stubs/contrib/postgres/fields/array.pyi

@@ -4,8 +4,9 @@ from typing import Any, TypeVar
 from django.core.validators import _ValidatorCallable
 from django.db.models import Field, Transform
 from django.db.models.expressions import Combinable, Expression
-from django.db.models.fields import NOT_PROVIDED, _ErrorMessagesDict, _ErrorMessagesMapping, _FieldChoices
+from django.db.models.fields import NOT_PROVIDED, _ErrorMessagesDict, _ErrorMessagesMapping
 from django.db.models.fields.mixins import CheckFieldDefaultMixin
+from django.utils.choices import _Choices
 from django.utils.functional import _StrOrPromise
 
 # __set__ value type
@@ -44,7 +45,7 @@ class ArrayField(CheckFieldDefaultMixin, Field[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,

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

@@ -15,6 +15,7 @@ from django.db.models.expressions import Col, Combinable, Expression
 from django.db.models.fields.reverse_related import ForeignObjectRel
 from django.db.models.query_utils import Q, RegisterLookupMixin
 from django.forms import Widget
+from django.utils.choices import BlankChoiceIterator, _Choice, _ChoiceNamedGroup, _Choices, _ChoicesCallable
 from django.utils.datastructures import DictWrapper
 from django.utils.functional import _Getter, _StrOrPromise, cached_property
 from typing_extensions import Self, TypeAlias
@@ -24,19 +25,11 @@ class NOT_PROVIDED: ...
 
 BLANK_CHOICE_DASH: list[tuple[str, str]]
 
-_Choice: TypeAlias = tuple[Any, Any]
-
-_ChoiceNamedGroup: TypeAlias = tuple[str, Iterable[_Choice]]
-_FieldChoices: TypeAlias = Iterable[_Choice | _ChoiceNamedGroup]
 _ChoicesList: TypeAlias = Sequence[_Choice] | Sequence[_ChoiceNamedGroup]
 _LimitChoicesTo: TypeAlias = Q | dict[str, Any]
 
 _F = TypeVar("_F", bound=Field, covariant=True)
 
-@type_check_only
-class _ChoicesCallable(Protocol):
-    def __call__(self) -> _FieldChoices: ...
-
 @type_check_only
 class _FieldDescriptor(Protocol[_F]):
     """
@@ -175,7 +168,7 @@ class Field(RegisterLookupMixin, Generic[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_tablespace: str | None = ...,
@@ -227,7 +220,7 @@ class Field(RegisterLookupMixin, Generic[_ST, _GT]):
         blank_choice: _ChoicesList = ...,
         limit_choices_to: _LimitChoicesTo | None = ...,
         ordering: Sequence[str] = ...,
-    ) -> _ChoicesList: ...
+    ) -> BlankChoiceIterator | _ChoicesList: ...
     def _get_flatchoices(self) -> list[_Choice]: ...
     @property
     def flatchoices(self) -> list[_Choice]: ...
@@ -288,7 +281,7 @@ class DecimalField(Field[_ST, _GT]):
         editable: bool = ...,
         auto_created: bool = ...,
         serialize: bool = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -320,7 +313,7 @@ class CharField(Field[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -350,7 +343,7 @@ class SlugField(CharField[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -385,7 +378,7 @@ class URLField(CharField[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -418,7 +411,7 @@ class TextField(Field[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -466,7 +459,7 @@ class GenericIPAddressField(Field[_ST, _GT]):
         editable: bool = ...,
         auto_created: bool = ...,
         serialize: bool = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -501,7 +494,7 @@ class DateField(DateTimeCheckMixin, Field[_ST, _GT]):
         editable: bool = ...,
         auto_created: bool = ...,
         serialize: bool = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -532,7 +525,7 @@ class TimeField(DateTimeCheckMixin, Field[_ST, _GT]):
         editable: bool = ...,
         auto_created: bool = ...,
         serialize: bool = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -569,7 +562,7 @@ class UUIDField(Field[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,
@@ -606,7 +599,7 @@ class FilePathField(Field[_ST, _GT]):
         editable: bool = ...,
         auto_created: bool = ...,
         serialize: bool = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,

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

@@ -7,10 +7,11 @@ from django.core.files.images import ImageFile
 from django.core.files.storage import Storage
 from django.db.models.base import Model
 from django.db.models.expressions import Expression
-from django.db.models.fields import NOT_PROVIDED, Field, _ErrorMessagesMapping, _FieldChoices
+from django.db.models.fields import NOT_PROVIDED, Field, _ErrorMessagesMapping
 from django.db.models.query_utils import DeferredAttribute
 from django.db.models.utils import AltersData
 from django.utils._os import _PathCompatible
+from django.utils.choices import _Choices
 from django.utils.functional import _StrOrPromise
 from typing_extensions import Self
 
@@ -71,7 +72,7 @@ class FileField(Field):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,

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

@@ -4,8 +4,9 @@ from django.core.validators import _ValidatorCallable
 from django.db import models
 from django.db.backends.base.base import BaseDatabaseWrapper
 from django.db.models.expressions import Expression
-from django.db.models.fields import _ErrorMessagesMapping, _FieldChoices
+from django.db.models.fields import _ErrorMessagesMapping
 from django.db.models.sql import Query
+from django.utils.choices import _Choices
 from django.utils.datastructures import DictWrapper
 from django.utils.functional import _StrOrPromise
 
@@ -34,7 +35,7 @@ class GeneratedField(models.Field):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_comment: str | None = ...,

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

@@ -5,14 +5,7 @@ from uuid import UUID
 from django.core import validators  # due to weird mypy.stubtest error
 from django.db.models.base import Model
 from django.db.models.expressions import Combinable, Expression
-from django.db.models.fields import (
-    NOT_PROVIDED,
-    Field,
-    _AllLimitChoicesTo,
-    _ErrorMessagesMapping,
-    _FieldChoices,
-    _LimitChoicesTo,
-)
+from django.db.models.fields import NOT_PROVIDED, Field, _AllLimitChoicesTo, _ErrorMessagesMapping, _LimitChoicesTo
 from django.db.models.fields.mixins import FieldCacheMixin
 from django.db.models.fields.related_descriptors import ForwardManyToOneDescriptor as ForwardManyToOneDescriptor
 from django.db.models.fields.related_descriptors import ForwardOneToOneDescriptor as ForwardOneToOneDescriptor
@@ -25,6 +18,7 @@ from django.db.models.fields.reverse_related import ManyToManyRel as ManyToManyR
 from django.db.models.fields.reverse_related import ManyToOneRel as ManyToOneRel
 from django.db.models.fields.reverse_related import OneToOneRel as OneToOneRel
 from django.db.models.query_utils import FilteredRelation, PathInfo, Q
+from django.utils.choices import _Choices
 from django.utils.functional import _StrOrPromise, cached_property
 from typing_extensions import Self
 
@@ -69,7 +63,7 @@ class RelatedField(FieldCacheMixin, Field[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_tablespace: str | None = ...,
@@ -122,7 +116,7 @@ class ForeignObject(RelatedField[_ST, _GT]):
         editable: bool = ...,
         auto_created: bool = ...,
         serialize: bool = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_tablespace: str | None = ...,
@@ -182,7 +176,7 @@ class ForeignKey(ForeignObject[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_tablespace: str | None = ...,
@@ -224,7 +218,7 @@ class OneToOneField(ForeignKey[_ST, _GT]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_tablespace: str | None = ...,
@@ -284,7 +278,7 @@ class ManyToManyField(RelatedField[Any, Any], Generic[_To, _Through]):
         unique_for_date: str | None = ...,
         unique_for_month: str | None = ...,
         unique_for_year: str | None = ...,
-        choices: _FieldChoices | None = ...,
+        choices: _Choices | None = ...,
         help_text: _StrOrPromise = ...,
         db_column: str | None = ...,
         db_tablespace: str | None = ...,

django-stubs/forms/fields.pyi

@@ -7,17 +7,11 @@ from uuid import UUID
 
 from django.core.files import File
 from django.core.validators import _ValidatorCallable
-from django.db.models.fields import (
-    _Choice,
-    _ChoiceNamedGroup,
-    _ChoicesCallable,
-    _ErrorMessagesDict,
-    _ErrorMessagesMapping,
-    _FieldChoices,
-)
+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.datastructures import _PropertyDescriptor
 from django.utils.functional import _StrOrPromise
 from typing_extensions import TypeAlias
@@ -320,21 +314,16 @@ class NullBooleanField(BooleanField):
     def to_python(self, value: Any | None) -> bool | None: ...  # type: ignore[override]
     def validate(self, value: Any) -> None: ...
 
-class CallableChoiceIterator:
-    choices_func: _ChoicesCallable
-    def __init__(self, choices_func: _ChoicesCallable) -> None: ...
-    def __iter__(self) -> Iterator[_Choice | _ChoiceNamedGroup]: ...
-
 class ChoiceField(Field):
     choices: _PropertyDescriptor[
-        _FieldChoices | _ChoicesCallable | CallableChoiceIterator,
-        _FieldChoices | CallableChoiceIterator,
+        _Choices | _ChoicesCallable | CallableChoiceIterator,
+        _Choices | CallableChoiceIterator,
     ]
     widget: _ClassLevelWidgetT
     def __init__(
         self,
         *,
-        choices: _FieldChoices | _ChoicesCallable = ...,
+        choices: _Choices | _ChoicesCallable = ...,
         required: bool = ...,
         widget: Widget | type[Widget] | None = ...,
         label: _StrOrPromise | None = ...,
@@ -365,7 +354,7 @@ class TypedChoiceField(ChoiceField):
         *,
         coerce: _CoerceCallable = ...,
         empty_value: str | None = ...,
-        choices: _FieldChoices | _ChoicesCallable = ...,
+        choices: _Choices | _ChoicesCallable = ...,
         required: bool = ...,
         widget: Widget | type[Widget] | None = ...,
         label: _StrOrPromise | None = ...,
@@ -393,7 +382,7 @@ class TypedMultipleChoiceField(MultipleChoiceField):
         *,
         coerce: _CoerceCallable = ...,
         empty_value: list[Any] | None = ...,
-        choices: _FieldChoices | _ChoicesCallable = ...,
+        choices: _Choices | _ChoicesCallable = ...,
         required: bool = ...,
         widget: Widget | type[Widget] | None = ...,
         label: _StrOrPromise | None = ...,
@@ -469,7 +458,7 @@ class FilePathField(ChoiceField):
         recursive: bool = ...,
         allow_files: bool = ...,
         allow_folders: bool = ...,
-        choices: _FieldChoices | _ChoicesCallable = ...,
+        choices: _Choices | _ChoicesCallable = ...,
         required: bool = ...,
         widget: Widget | type[Widget] | None = ...,
         label: _StrOrPromise | None = ...,