Initial support for PEP 695 type aliases #13508
Conversation
mmatous
force-pushed
the
pep695
branch
4 times, most recently
from
89caa94 to
ef7dbce
Compare
|
Thanks Martin! Please could you resolve conflicts? cc also @picnixz if you want to have a look. A |
|
done |
sphinx/ext/autodoc/__init__.py
Outdated
| @@ -1693,7 +1698,7 @@ def can_document_member( | |||
| cls: type[Documenter], member: Any, membername: str, isattr: bool, parent: Any | |||
| ) -> bool: | |||
| return isinstance(member, type) or ( | |||
| isattr and isinstance(member, NewType | TypeVar) | |||
| isattr and isinstance(member, NewType | TypeVar | TypeAliasType) | |||
There was a problem hiding this comment.
Would it be possible to create a private helper say def _is_typelike(s): return isinstance(s, NewType | TypeVar | TypeAliasType)? that way, we can avoid having to add more and more types in the union in the future.
There was a problem hiding this comment.
Created the helper as static method. To make mypy happy I had to delete type-hint for cls (or use type: ignore). I'm guessing it's fine and the reason for cls having a type is because the code predates some tooling feature like cls type autodetect or Documenter itself predating ABCs and abstractmethods?
In any case, it didn't seem to break anything.
| class Foo: | ||
| """This is class Foo.""" | ||
|
|
||
| ... |
There was a problem hiding this comment.
Let's address ruff's issues here (remove "...")
| type Pep695Alias = Foo | ||
| """This is PEP695 type alias.""" | ||
|
|
||
| type Pep695AliasC = dict[str, Foo] #: This is PEP695 complex type alias with doc comment. |
There was a problem hiding this comment.
Change the ruff configuration so that this test file requires python 3.12 as the target version: https://docs.astral.sh/ruff/settings/#per-file-target-version.
| reason='PEP 695 is Python 3.12 feature. Older versions fail to parse source into AST.', | ||
| ) | ||
| @pytest.mark.sphinx('html', testroot='ext-autodoc') | ||
| def test_autodoc_Pep695Alias(app): |
There was a problem hiding this comment.
| def test_autodoc_Pep695Alias(app): | |
| def test_autodoc_pep695_type_alias(app): |
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).
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.
I'm surprised: the parser actually supports this. But cross-referencing may not be entirely supported though. |
mmatous
force-pushed
the
pep695
branch
3 times, most recently
from
042c7ec to
74e759d
Compare
Signed-off-by: Martin Matous <[email protected]>
|
Updated with requested changes.
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. |
| @@ -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): | |||
There was a problem hiding this comment.
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.
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 invisit_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
ClassDocumentersince 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 onlytype A = list[T]in resulting HTML. This seems expected, since there is no supported syntax for type params inpy:type, unlikepy:methodDoes 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