Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Correctly parse and cross-reference unpacked type annotations #13369

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Correctly parse and cross-reference unpacked type annotations #13369

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGES.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,5 +16,8 @@ Features added
Bugs fixed
----------

* #13369: Correctly parse and cross-reference unpacked type annotations.
Patch by Alicia Garcia-Raboso.

Testing
-------
4 changes: 4 additions & 0 deletions sphinx/domains/python/_annotations.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
3 changes: 3 additions & 0 deletions sphinx/pycode/ast.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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__)
22 changes: 22 additions & 0 deletions tests/test_domains/test_domain_py.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -508,6 +508,28 @@ def test_parse_annotation(app):
),
)

doctree = _parse_annotation('*tuple[str, int]', app.env)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is *tuple[...] a valid stand-alone type annotation? If not, should we have some validation that Starred only comes after [?

I'm happy to keep things as currently proposed in this PR, just unsure which is the best approach.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is valid in the context of variadic generics annotations (see https://peps.python.org/pep-0646/#unpacking-tuple-types). In other places it is not, but I worked this out under the assumption that Sphinx is looking to accept all valid Python behaviors, not disallow non-valid ones (that would be neat, but would probably imply reimplementing a huge part of the parser in any Python implementation).

With respect to what you are saying about validating it only comes after [: I came out with this PR to deal with annotations in type signatures in function arguments, not in type parameter specifications alla PEP 695. I am AFK and I don't remember off the top of my head if it does come into parsing the latter. I will look into it as soon as I can.

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):
Expand Down
1 change: 1 addition & 0 deletions tests/test_pycode/test_pycode_ast.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down