Remove `sphinx.util.docfields` from the no-any-generics whitelist

pyproject.toml

@@ -234,7 +234,6 @@ module = [
     "sphinx.domains",
     "sphinx.domains.c",
     "sphinx.domains.cpp",
-    "sphinx.util.docfields",
     "sphinx.util.docutils",
     "sphinx.util.inspect",
     "sphinx.util.logging",

sphinx/util/docfields.py

@@ -17,7 +17,7 @@ from sphinx.util import logging
 from sphinx.util.nodes import get_node_line
 
 if TYPE_CHECKING:
-    from typing import Any
+    from typing import TypeAlias, TypeVar
 
     from docutils.nodes import Element, Node
     from docutils.parsers.rst.states import Inliner
@@ -26,6 +26,11 @@ if TYPE_CHECKING:
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import TextlikeNode
 
+    ObjDescT = TypeVar('ObjDescT')
+    _FieldEntry: TypeAlias = tuple[str, list[Node]]
+    _FieldTypes: TypeAlias = dict[str, list[Node]]
+    _EntriesTriple: TypeAlias = tuple['Field', _FieldEntry | list[_FieldEntry], Element]
+
 logger = logging.getLogger(__name__)
 
 
@@ -133,14 +138,14 @@ class Field:
             )
         ]
 
-    def make_entry(self, fieldarg: str, content: list[Node]) -> tuple[str, list[Node]]:
+    def make_entry(self, fieldarg: str, content: list[Node]) -> _FieldEntry:
         return fieldarg, content
 
     def make_field(
         self,
-        types: dict[str, list[Node]],
+        types: _FieldTypes,
         domain: str,
-        item: tuple,
+        item: _FieldEntry,
         env: BuildEnvironment | None = None,
         inliner: Inliner | None = None,
         location: Element | None = None,
@@ -211,9 +216,9 @@ class GroupedField(Field):
 
     def make_field(
         self,
-        types: dict[str, list[Node]],
+        types: _FieldTypes,
         domain: str,
-        items: tuple,
+        items: list[_FieldEntry],  # type: ignore[override]
         env: BuildEnvironment | None = None,
         inliner: Inliner | None = None,
         location: Element | None = None,
@@ -283,9 +288,9 @@ class TypedField(GroupedField):
 
     def make_field(
         self,
-        types: dict[str, list[Node]],
+        types: _FieldTypes,
         domain: str,
-        items: tuple,
+        items: list[_FieldEntry],  # type: ignore[override]
         env: BuildEnvironment | None = None,
         inliner: Inliner | None = None,
         location: Element | None = None,
@@ -344,7 +349,7 @@ class DocFieldTransformer:
 
     typemap: dict[str, tuple[Field, bool]]
 
-    def __init__(self, directive: ObjectDescription) -> None:
+    def __init__(self, directive: ObjectDescription[ObjDescT]) -> None:
         self.directive = directive
 
         self.typemap = directive.get_field_type_map()
@@ -358,14 +363,24 @@ class DocFieldTransformer:
 
     def transform(self, node: nodes.field_list) -> None:
         """Transform a single field list *node*."""
-        typemap = self.typemap
+        entries: list[nodes.field | _EntriesTriple] = []
-
-        entries: list[nodes.field | tuple[Field, Any, Element]] = []
         groupindices: dict[str, int] = {}
-        types: dict[str, dict] = {}
+        types: dict[str, _FieldTypes] = {}
 
         # step 1: traverse all fields and collect field types and content
         for field in cast('list[nodes.field]', node):
+            self._transform_step_1(field, entries, types, groupindices)
+
+        new_list = self._transform_step_2(entries, types)
+        node.replace_self(new_list)
+
+    def _transform_step_1(
+        self,
+        field: nodes.field,
+        entries: list[nodes.field | _EntriesTriple],
+        types: dict[str, _FieldTypes],
+        group_indices: dict[str, int],
+    ) -> None:
         assert len(field) == 2
         field_name = cast('nodes.field_name', field[0])
         field_body = cast('nodes.field_body', field[1])
@@ -375,7 +390,7 @@ class DocFieldTransformer:
         except ValueError:
             # maybe an argument-less field type?
             fieldtype_name, fieldarg = field_name.astext(), ''
-            typedesc, is_typefield = typemap.get(fieldtype_name, (None, None))
+        typedesc, is_typefield = self.typemap.get(fieldtype_name, (None, None))
 
         # collect the content, trying not to keep unnecessary paragraphs
         if _is_single_paragraph(field_body):
@@ -419,7 +434,7 @@ class DocFieldTransformer:
                     field_body.clear()
                     field_body += nodes.paragraph('', '', *xrefs)
 
-                continue
+            return
 
         typename = typedesc.name
 
@@ -427,12 +442,10 @@ class DocFieldTransformer:
         if is_typefield:
             # filter out only inline nodes; others will result in invalid
             # markup being written out
-                content = [
+            content = [n for n in content if isinstance(n, nodes.Inline | nodes.Text)]
-                    n for n in content if isinstance(n, nodes.Inline | nodes.Text)
-                ]
             if content:
                 types.setdefault(typename, {})[fieldarg] = content
-                continue
+            return
 
         # also support syntax like ``:param type name:``
         if typedesc.is_typed:
@@ -453,12 +466,13 @@ class DocFieldTransformer:
         # grouped entries need to be collected in one entry, while others
         # get one entry per field
         if typedesc.is_grouped:
-                if typename in groupindices:
+            if typename in group_indices:
                 group = cast(
-                        'tuple[Field, list, Node]', entries[groupindices[typename]]
+                    'tuple[Field, list[_FieldEntry], Node]',
+                    entries[group_indices[typename]],
                 )
             else:
-                    groupindices[typename] = len(entries)
+                group_indices[typename] = len(entries)
                 group = (typedesc, [], field)
                 entries.append(group)
             new_entry = typedesc.make_entry(fieldarg, [translatable_content])
@@ -467,6 +481,11 @@ class DocFieldTransformer:
             new_entry = typedesc.make_entry(fieldarg, [translatable_content])
             entries.append((typedesc, new_entry, field))
 
+    def _transform_step_2(
+        self,
+        entries: list[nodes.field | _EntriesTriple],
+        types: dict[str, _FieldTypes],
+    ) -> nodes.field_list:
         # step 2: all entries are collected, construct the new field list
         new_list = nodes.field_list()
         for entry in entries:
@@ -482,10 +501,10 @@ class DocFieldTransformer:
                 new_list += fieldtype.make_field(
                     fieldtypes,
                     domain,
-                    items,
+                    items,  # type: ignore[arg-type]
                     env=env,
                     inliner=inliner,
                     location=location,
                 )
 
-        node.replace_self(new_list)
+        return new_list