Skip to content

Initial support for PEP 695 type aliases #13508

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.

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

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

Conversation

mmatous
Copy link

@mmatous mmatous commented Apr 25, 2025

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

@mmatous mmatous force-pushed the pep695 branch 3 times, most recently from 58aee82 to 89caa94 Compare April 26, 2025 00:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant