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.

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

Author: ngnpope

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]

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
 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) -> list[_DisplayT]: ...
+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]]: ...

tests/assert_type/contrib/admin/test_utils.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Any
+
+from django import http
+from django.contrib import admin
+from django.contrib.admin.options import _DisplayT, _ListDisplayT
+from django.contrib.admin.utils import flatten, flatten_fieldsets
+from django.db import models
+from typing_extensions import assert_type
+
+
+@admin.display(description="Name")
+def upper_case_name(obj: Person) -> str:
+    return f"{obj.first_name} {obj.last_name}".upper()  # pyright: ignore[reportUnknownMemberType]
+
+
+class Person(models.Model):
+    first_name = models.CharField(max_length=None)  # pyright: ignore[reportUnknownVariableType]
+    last_name = models.CharField(max_length=None)  # pyright: ignore[reportUnknownVariableType]
+    birthday = models.DateField()  # pyright: ignore[reportUnknownVariableType]
+
+
+class PersonListAdmin(admin.ModelAdmin[Person]):
+    fields = [["first_name", "last_name"], "birthday"]
+    list_display = [upper_case_name, "birthday"]
+
+
+class PersonTupleAdmin(admin.ModelAdmin[Person]):
+    fields = (("first_name", "last_name"), "birthday")
+    # Explicit typing required in this case where we have a `tuple`.
+    # Without it, this effectively becomes `tuple[object, ...]`.
+    # This is because of the whole mypy join vs union issue.
+    # See https://github.com/python/mypy/issues?q=is%3Aissue%20state%3Aopen%20label%3Atopic-join-v-union
+    list_display: _ListDisplayT = (upper_case_name, "birthday")
+
+
+class PersonFieldsetListAdmin(admin.ModelAdmin[Person]):
+    fieldsets = [
+        (
+            "Personal Details",
+            {
+                "description": "Personal details of a person.",
+                "fields": [["first_name", "last_name"], "birthday"],
+            },
+        )
+    ]
+
+
+class PersonFieldsetTupleAdmin(admin.ModelAdmin[Person]):
+    fieldsets = (
+        (
+            "Personal Details",
+            {
+                "description": "Personal details of a person.",
+                "fields": (("first_name", "last_name"), "birthday"),
+            },
+        ),
+    )
+
+
+request = http.HttpRequest()
+admin_site = admin.AdminSite()
+person_list_admin = PersonListAdmin(Person, admin_site)
+person_tuple_admin = PersonTupleAdmin(Person, admin_site)
+person_fieldset_list_admin = PersonFieldsetListAdmin(Person, admin_site)
+person_fieldset_tuple_admin = PersonFieldsetTupleAdmin(Person, admin_site)
+
+# For some reason, pyright cannot see that these are defined.
+assert person_list_admin.fields is not None
+assert person_tuple_admin.fields is not None
+assert person_fieldset_list_admin.fieldsets is not None
+assert person_fieldset_tuple_admin.fieldsets is not None
+
+assert_type(flatten(person_list_admin.fields), list[str])
+assert_type(flatten(person_list_admin.get_fields(request)), list[str])
+assert_type(flatten(person_tuple_admin.fields), list[str])
+assert_type(flatten(person_tuple_admin.get_fields(request)), list[str])
+
+# Currently `_ModelT` appears to be `Any` instead of `Person`.
+assert_type(flatten(person_list_admin.list_display), list[_DisplayT[Any]])
+assert_type(flatten(person_list_admin.get_list_display(request)), list[_DisplayT[Any]])
+assert_type(flatten(person_tuple_admin.list_display), list[_DisplayT[Any]])
+assert_type(flatten(person_tuple_admin.get_list_display(request)), list[_DisplayT[Any]])
+
+assert_type(flatten_fieldsets(person_fieldset_list_admin.fieldsets), list[str])
+assert_type(flatten_fieldsets(person_fieldset_list_admin.get_fieldsets(request)), list[str])
+assert_type(flatten_fieldsets(person_fieldset_tuple_admin.fieldsets), list[str])
+assert_type(flatten_fieldsets(person_fieldset_tuple_admin.get_fieldsets(request)), list[str])