Initial support for PEP 695 type aliases #13508

mmatous · 2025-04-25T23:53:58Z

Purpose

Hi, this PR includes support for documenting PEP 695 type aliases. The main problem was that while looking for docstrings, Sphinx's parser didn't recognize ast.TypeAlias as visitable (for doc comment, missing visit_TypeAlias()) and TypeAliasType object wasn't recognized as something documentable when encountering docstring in visit_Expr() (for docstrings).

The rest of it is mostly just me guessing how stuff should be rendered into ReST and trying to ensure Python 3.11 compatibility.

I put the relevant autodoc parts into ClassDocumenter since that's where code for other type alias variants lives.

Couple of caveats:

Type aliases in signatures don't get cross-linked in HTML. I could use some pointers here. I think the ReST is mostly fine and the problem lies in HTML gen.? What should I do about that?
Generic type aliases do not get rendered as such. E.g. type A[T] = list[T] yields only type A = list[T] in resulting HTML. This seems expected, since there is no supported syntax for type params in py:type, unlike py:method
Does not include support for PEP 695 type parameters in generic classes (class ClassA[T: str]:) or functions/methods (def func[T](a: T, b: T) -> T:). I thought about it briefly and it seems more complicated than I'm willing to tackle rn.
How should I go about ruff accepting the test file? Add exemption to pyproject? SyntaxError bc of targeting Py3.11 can't be suppressed.

References

requested in autodoc: Add support for PEP 695's explicit type aliases #11561

AA-Turner · 2025-05-13T10:20:48Z

Thanks Martin! Please could you resolve conflicts?

cc also @picnixz if you want to have a look.

A

mmatous · 2025-05-14T12:59:51Z

done

picnixz

I'm surprised by how easy it was to add this support...

sphinx/ext/autodoc/__init__.py

tests/roots/test-ext-autodoc/target/pep695.py

tests/test_extensions/test_ext_autodoc.py

picnixz · 2025-05-15T17:13:07Z

Type aliases in signatures don't get cross-linked in HTML. I could use some pointers here

That's probably because of how we parse the signature. This is a part I wrote so I could try to help you later this week (I'm sorry I got disconnected quite a lot with Sphinx now that I'm contributing directly to CPython).

type A[T] = list[T] yields only type A = list[T] in resulting HTML. This seems expected, since there is no supported syntax for type params in py:type, unlike py:method

Again that's me who wrote that part for method and the rest. We didn't have the type directive yet and I think I forgot to update this. There's an open issue somewhere where I said I'll take care of it but I forgot. My bad.

Does not include support for PEP 695 type parameters in generic classes (class ClassA[T: str]:)

I'm surprised: the parser actually supports this. But cross-referencing may not be entirely supported though.

Signed-off-by: Martin Matous <m@matous.dev>

mmatous · 2025-05-21T02:24:42Z

Updated with requested changes.

This is a part I wrote so I could try to help you later this week

The links would be nice. I'd like to incorporate them in this PR provided the necessary changes are small enough. If it's more work I'll still make them happen, but I wouldn't want this PR to be bogged down because of it. Just point me in the right direction for now. I'll figure it out.

Viicos · 2025-05-22T14:14:38Z

sphinx/ext/autodoc/__init__.py

@@ -1942,6 +1951,11 @@ def add_directive_header(self, sig: str) -> None:
        ):
            self.add_line('   :canonical: %s' % canonical_fullname, sourcename)

+        if isinstance(self.object, TypeAliasType):


typing_extensions.TypeAliasType is a different object than typing.TypeAliasType (even on 3.12 where both exist).

See litestar-org/litestar#3982 (comment) for more details.

Thank you. Doesn't seem relevant in this context, though. Only one of them will be imported at any given time (0912a5e#diff-e43bdd6f8f37a12d2536e09e57c5e8999cb8de18b9c7ba49126f90576c4328acR57), so the parsed code will always be interpreted consistently as either one or the other.

Is there a way for the above if to be executed? also, not isinstance(self.object, NewType) is always true so we should remove it. I just don't want to add 2 canonical lines. So we should first check for TypeAliasType first maybe.

picnixz

I don't have a lot of time, but here's another round of review.

picnixz · 2025-07-28T12:27:57Z

CHANGES.rst

@@ -25,6 +25,8 @@ Features added
 * #13704: autodoc: Detect :py:func:`typing_extensions.overload <typing.overload>`
  and :py:func:`~typing.final` decorators.
  Patch by Spencer Brown.
+* #13508: Initial support for PEP 695 type aliases.


Suggested change

* #13508: Initial support for PEP 695 type aliases.

* #13508: Initial support for :pep:`695` type aliases.

picnixz · 2025-07-28T12:31:45Z

sphinx/ext/autodoc/__init__.py

@@ -1942,6 +1951,11 @@ def add_directive_header(self, sig: str) -> None:
        ):
            self.add_line('   :canonical: %s' % canonical_fullname, sourcename)

+        if isinstance(self.object, TypeAliasType):


Is there a way for the above if to be executed? also, not isinstance(self.object, NewType) is always true so we should remove it. I just don't want to add 2 canonical lines. So we should first check for TypeAliasType first maybe.

picnixz · 2025-07-28T12:32:35Z

sphinx/pycode/parser.py

+    def collect_doc_comment(
+        self,
+        # exists for >= 3.12, irrelevant for runtime
+        node: ast.Assign | ast.TypeAlias,  # type: ignore[name-defined]


I don't really like this suppression so how about having an "AssignmentLike = ast.Assign" for < 3.12 and AssignmentLike = ast.Assign | ast.TypeAlias for >= 3.12 and use such annotation?

picnixz · 2025-07-28T12:34:56Z

sphinx/pycode/parser.py

+        # check comments before assignment
+        if indent_re.match(current_line[: node.col_offset]):
+            comment_lines = []
+            for i in range(node.lineno - 1):


instead of going from 0 to node.lineno - 2 and compute node.lineno - 1 - i, why not using a reversed range?

picnixz · 2025-07-28T13:24:45Z

sphinx/pycode/parser.py

+        if (sys.version_info[:2] >= (3, 12)) and isinstance(
+            self.previous, ast.TypeAlias
+        ):


Suggested change

if (sys.version_info[:2] >= (3, 12)) and isinstance(

self.previous, ast.TypeAlias

):

elif (sys.version_info[:2] >= (3, 12)) and isinstance(

self.previous, ast.TypeAlias

):

mmatous force-pushed the pep695 branch 4 times, most recently from 89caa94 to ef7dbce Compare April 26, 2025 00:25

mmatous force-pushed the pep695 branch from ef7dbce to 4c2ae82 Compare May 14, 2025 12:47

picnixz self-requested a review May 15, 2025 17:05

picnixz reviewed May 15, 2025

View reviewed changes

mmatous force-pushed the pep695 branch 3 times, most recently from 042c7ec to 74e759d Compare May 21, 2025 01:55

Initial support for PEP 695 type aliases

0912a5e

Signed-off-by: Martin Matous <m@matous.dev>

mmatous force-pushed the pep695 branch from 74e759d to 0912a5e Compare May 21, 2025 02:10

Viicos reviewed May 22, 2025

View reviewed changes

AA-Turner requested a review from picnixz July 28, 2025 11:33

AA-Turner added the extensions:autodoc label Jul 28, 2025

picnixz reviewed Jul 28, 2025

View reviewed changes

AA-Turner added 3 commits July 29, 2025 03:43

Merge branch 'master' into pep695

284a1b3

Merge branch 'master' into pep695

d213f88

_is_type_like()

67c721f

	* #13508: Initial support for PEP 695 type aliases.
	* #13508: Initial support for :pep:`695` type aliases.

Uh oh!

Initial support for PEP 695 type aliases #13508

Are you sure you want to change the base?

Initial support for PEP 695 type aliases #13508

Uh oh!

Conversation

mmatous commented Apr 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose

References

Uh oh!

AA-Turner commented May 13, 2025

Uh oh!

mmatous commented May 14, 2025

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

picnixz commented May 15, 2025

Uh oh!

mmatous commented May 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mmatous commented Apr 25, 2025 •

edited

Loading