Correctly parse and cross-reference unpacked type annotations

Author: agraboso

sphinx/domains/python/_annotations.py

@@ -124,6 +124,10 @@ def unparse(node: ast.AST) -> list[Node]:
                 return [nodes.Text(repr(node.value))]
         if isinstance(node, ast.Expr):
             return unparse(node.value)
+        if isinstance(node, ast.Starred):
+            result = [addnodes.desc_sig_operator('', '*')]
+            result.extend(unparse(node.value))
+            return result
         if isinstance(node, ast.Invert):
             return [addnodes.desc_sig_punctuation('', '~')]
         if isinstance(node, ast.USub):

sphinx/pycode/ast.py

@@ -202,5 +202,8 @@ def visit_Tuple(self, node: ast.Tuple) -> str:
         else:
             return '(' + ', '.join(self.visit(e) for e in node.elts) + ')'
 
+    def visit_Starred(self, node: ast.Starred) -> str:
+        return f'*{self.visit(node.value)}'
+
     def generic_visit(self, node: ast.AST) -> NoReturn:
         raise NotImplementedError('Unable to parse %s object' % type(node).__name__)

tests/test_domains/test_domain_py.py

@@ -508,6 +508,28 @@ def test_parse_annotation(app):
         ),
     )
 
+    doctree = _parse_annotation('*tuple[str, int]', app.env)
+    assert_node(
+        doctree,
+        (
+            [desc_sig_operator, '*'],
+            [pending_xref, 'tuple'],
+            [desc_sig_punctuation, '['],
+            [pending_xref, 'str'],
+            [desc_sig_punctuation, ','],
+            desc_sig_space,
+            [pending_xref, 'int'],
+            [desc_sig_punctuation, ']'],
+        ),
+    )
+    assert_node(
+        doctree[1],
+        pending_xref,
+        refdomain='py',
+        reftype='class',
+        reftarget='tuple',
+    )
+
 
 @pytest.mark.sphinx('html', testroot='_blank')
 def test_parse_annotation_suppress(app):

tests/test_pycode/test_pycode_ast.py

@@ -62,6 +62,7 @@
          'x[:, np.newaxis, :, :]'),                # Index, Subscript, numpy extended syntax
         ('y[:, 1:3][np.array([0, 2, 4]), :]',
          'y[:, 1:3][np.array([0, 2, 4]), :]'),     # Index, 2x Subscript, numpy extended syntax
+        ('*tuple[str, int]', '*tuple[str, int]'),  # Starred
     ],
 )  # fmt: skip
 def test_unparse(source, expected):