Merge pull request #8646 from tk0miya/refactor_typehints

refactor: Update typehints for ObjectDescription using Generic

sphinx/directives/__init__.py

@@ -9,7 +9,7 @@
 """
 
 import re
-from typing import Any, Dict, List, Tuple, cast
+from typing import Any, Dict, Generic, List, Tuple, TypeVar, cast
 
 from docutils import nodes
 from docutils.nodes import Node
@@ -33,6 +33,8 @@ if False:
 nl_escape_re = re.compile(r'\\\n')
 strip_backslash_re = re.compile(r'\\(.)')
 
+T = TypeVar('T')
+
 
 def optional_int(argument: str) -> int:
     """
@@ -47,7 +49,7 @@ def optional_int(argument: str) -> int:
         return value
 
 
-class ObjectDescription(SphinxDirective):
+class ObjectDescription(SphinxDirective, Generic[T]):
     """
     Directive to describe a class, function or similar object.  Not used
     directly, but subclassed (in domain-specific directives) to add custom
@@ -97,7 +99,7 @@ class ObjectDescription(SphinxDirective):
         else:
             return [line.strip() for line in lines]
 
-    def handle_signature(self, sig: str, signode: desc_signature) -> Any:
+    def handle_signature(self, sig: str, signode: desc_signature) -> T:
         """
         Parse the signature *sig* into individual nodes and append them to
         *signode*. If ValueError is raised, parsing is aborted and the whole
@@ -109,7 +111,7 @@ class ObjectDescription(SphinxDirective):
         """
         raise ValueError
 
-    def add_target_and_index(self, name: Any, sig: str, signode: desc_signature) -> None:
+    def add_target_and_index(self, name: T, sig: str, signode: desc_signature) -> None:
         """
         Add cross-reference IDs and entries to self.indexnode, if applicable.
 
@@ -173,7 +175,7 @@ class ObjectDescription(SphinxDirective):
         if self.domain:
             node['classes'].append(self.domain)
 
-        self.names = []  # type: List[Any]
+        self.names = []  # type: List[T]
         signatures = self.get_signatures()
         for i, sig in enumerate(signatures):
             # add a signature node for each signature in the current unit

sphinx/domains/c.py

@@ -3099,7 +3099,7 @@ def _make_phony_error_name() -> ASTNestedName:
     return ASTNestedName([ASTIdentifier("PhonyNameDueToError")], rooted=False)
 
 
-class CObject(ObjectDescription):
+class CObject(ObjectDescription[ASTDeclaration]):
     """
     Description of a C language object.
     """

sphinx/domains/cpp.py

@@ -6670,7 +6670,7 @@ def _make_phony_error_name() -> ASTNestedName:
     return ASTNestedName([nne], [False], rooted=False)
 
 
-class CPPObject(ObjectDescription):
+class CPPObject(ObjectDescription[ASTDeclaration]):
     """Description of a C++ language object."""
 
     doc_field_types = [

sphinx/domains/javascript.py

@@ -32,7 +32,7 @@ from sphinx.util.nodes import make_id, make_refnode
 logger = logging.getLogger(__name__)
 
 
-class JSObject(ObjectDescription):
+class JSObject(ObjectDescription[Tuple[str, str]]):
     """
     Description of a JavaScript object.
     """

sphinx/domains/python.py

@@ -334,7 +334,7 @@ class PyTypedField(PyXrefMixin, TypedField):
         return super().make_xref(rolename, domain, target, innernode, contnode, env)
 
 
-class PyObject(ObjectDescription):
+class PyObject(ObjectDescription[Tuple[str, str]]):
     """
     Description of a general Python object.
 

sphinx/domains/rst.py

@@ -31,7 +31,7 @@ logger = logging.getLogger(__name__)
 dir_sig_re = re.compile(r'\.\. (.+?)::(.*)$')
 
 
-class ReSTMarkup(ObjectDescription):
+class ReSTMarkup(ObjectDescription[str]):
     """
     Description of generic reST markup.
     """

sphinx/domains/std.py

@@ -48,7 +48,7 @@ option_desc_re = re.compile(r'((?:/|--|-|\+)?[^\s=]+)(=?\s*.*)')
 token_re = re.compile(r'`(\w+)`', re.U)
 
 
-class GenericObject(ObjectDescription):
+class GenericObject(ObjectDescription[str]):
     """
     A generic x-ref directive registered with Sphinx.add_object_type().
     """
@@ -178,7 +178,7 @@ class Target(SphinxDirective):
         return self.name + '-' + name
 
 
-class Cmdoption(ObjectDescription):
+class Cmdoption(ObjectDescription[str]):
     """
     Description of a command-line option (.. option).
     """