IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Adam Turner 2025-01-22 20:13:44 +00:00
parent 14db5ffba1
commit 705cf7fcf5
2 changed files with 128 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
pyproject.toml
View File

@ -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",

67
sphinx/util/docfields.py
View File

@ -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 | tuple[Field, Any, Element]] = []
entries: list[nodes.field | _EntriesTriple] = []
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 = [
n for n in content if isinstance(n, nodes.Inline | nodes.Text)
]
content = [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