Improve stubs for flatten and flatten_fieldsets

These functions are implemented in a generic way that doesn't
generally care about the content. The existing return type of
`Callable | str` makes these awkward to use.

I've changed the use of `Sequence` in the `_FieldGroups` alias to use
`_ListOrTuple`. This is another case where `ModelAdmin.fields` and the
`"fields"` item in fieldsets are presumed by Django to be a `list` or
`tuple`, e.g. there are some system checks that ensure this.

I've also made `_FieldGroups` and `_FieldsetSpec` generic so that these
aliases can be reused by `flatten()` and `flatten_fieldsets()`. Because
of this, the typing of these functions will also now work nicely if used
with `.list_display`, `.readonly_fields`, etc.

See https://github.com/django/django/blob/afbb8c709d40e77b3f71c152d363c5ad95ceec2d/django/contrib/admin/utils.py#L102-L120

Author: ngnpope

django-stubs/contrib/admin/options.pyi

@@ -56,21 +56,19 @@ class IncorrectLookupParameters(Exception): ...
 FORMFIELD_FOR_DBFIELD_DEFAULTS: Any
 csrf_protect_m: Any
 
-_FieldGroups: TypeAlias = Sequence[str | Sequence[str]]
+_FieldT = TypeVar("_FieldT")
+_FieldGroups: TypeAlias = _ListOrTuple[_FieldT | _ListOrTuple[_FieldT]]
 
 @type_check_only
 class _OptionalFieldOpts(TypedDict, total=False):
     classes: Sequence[str]
     description: _StrOrPromise
 
 @type_check_only
-class _FieldOpts(_OptionalFieldOpts, total=True):
-    fields: _FieldGroups
+class _FieldOpts(_OptionalFieldOpts, Generic[_FieldT], total=True):
+    fields: _FieldGroups[_FieldT]
 
-# 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]]
+_FieldsetSpec: TypeAlias = _ListOrTuple[tuple[_StrOrPromise | None, _FieldOpts[_FieldT]]]
 _ListFilterT: TypeAlias = (
     type[ListFilter]
     | Field[Any, Any]
@@ -89,9 +87,9 @@ _DisplayT: TypeAlias = _ListOrTuple[str | Callable[[_ModelT], str | bool]]
 class BaseModelAdmin(Generic[_ModelT]):
     autocomplete_fields: ClassVar[_ListOrTuple[str]]
     raw_id_fields: ClassVar[_ListOrTuple[str]]
-    fields: ClassVar[_FieldGroups | None]
+    fields: ClassVar[_FieldGroups[str] | None]
     exclude: ClassVar[_ListOrTuple[str] | None]
-    fieldsets: ClassVar[_FieldsetSpec | None]
+    fieldsets: ClassVar[_FieldsetSpec[str] | None]
     form: type[forms.ModelForm[_ModelT]]
     filter_vertical: ClassVar[_ListOrTuple[str]]
     filter_horizontal: ClassVar[_ListOrTuple[str]]
@@ -123,8 +121,8 @@ class BaseModelAdmin(Generic[_ModelT]):
     def get_view_on_site_url(self, obj: _ModelT | None = ...) -> str | None: ...
     def get_empty_value_display(self) -> SafeString: ...
     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_fields(self, request: HttpRequest, obj: _ModelT | None = ...) -> _FieldGroups[str]: ...
+    def get_fieldsets(self, request: HttpRequest, obj: _ModelT | None = ...) -> _FieldsetSpec[str]: ...
     def get_inlines(self, request: HttpRequest, obj: _ModelT | None) -> list[type[InlineModelAdmin]]: ...
     def get_ordering(self, request: HttpRequest) -> _ListOrTuple[str]: ...
     def get_readonly_fields(self, request: HttpRequest, obj: _ModelT | None = ...) -> _ListOrTuple[str]: ...

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, _FieldGroups, _FieldsetSpec
 from django.contrib.admin.sites import AdminSite
 from django.db.models.base import Model
 from django.db.models.deletion import Collector
@@ -31,8 +31,8 @@ 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]: ...
+def flatten(fields: _FieldGroups[_T]) -> list[_T]: ...
+def flatten_fieldsets(fieldsets: _FieldsetSpec[_T]) -> list[_T]: ...
 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]]: ...