gh-112472 Improve typing docs intro for TypeAlias #114363
Conversation
Rowlando13
requested review from
JelleZijlstra and
AlexWaygood
as code owners
|
All commit authors signed the Contributor License Agreement. |
Doc/library/typing.rst
Outdated
| .. deprecated:: 3.12 | ||
| For reasoning see :data:`TypeAlias` |
There was a problem hiding this comment.
According to PEP 695 (maybe things have changed since then) TypeAlias is deprecated but not scheduled for removal. I believe this overlaps with the concept of soft deprecation introduced around the same time. I think it would make sense to write that TypeAlias is soft deprecated, but I'm not sure if there is an rst directive for that.
There was a problem hiding this comment.
Soft deprecation is probably a good fit here, yes.
Doc/library/typing.rst
Outdated
| Additionally and also for backward compatibility types can be marked with | ||
| :data:`TypeAlias`. :: |
There was a problem hiding this comment.
I think the notion of backwards compatibility could be specified further, as this discussion shows that the behaviour of the TypeAliasType is not entirely intuitive. We should specify that TypeAlias should be used when you want a type alias that behaves like a normal type at run-time. This may be evident to typing experts, but many are surprised by this behaviour.
There was a problem hiding this comment.
Agree we should mention the tradeoff here.
| specification of the typing system, see :pep:`484`. For a simplified | ||
| introduction to type hints, see :pep:`483`. | ||
|
|
||
| This module provides runtime support for type hints. |
There was a problem hiding this comment.
Not sure why this paragraph was changed; that seems unrelated to the purpose of the PR.
There was a problem hiding this comment.
This was changed because this section is repetitive. Almost the same text is 1 page scroll down on the same page.
Doc/library/typing.rst
Outdated
| .. deprecated:: 3.12 | ||
| For reasoning see :data:`TypeAlias` |
There was a problem hiding this comment.
Soft deprecation is probably a good fit here, yes.
Doc/library/typing.rst
Outdated
| Additionally and also for backward compatibility types can be marked with | ||
| :data:`TypeAlias`. :: |
There was a problem hiding this comment.
Agree we should mention the tradeoff here.
|
|
||
| Or marked with :data:`TypeAlias` to make it explicit that this is a type alias, | ||
| not a normal variable assignment:: | ||
| The following example is an expansion of the above that shows what is |
There was a problem hiding this comment.
I don't agree with this sentence and I don't think it clarifies the situation for new users.
|
The following commit authors need to sign the Contributor License Agreement: |
Remove redundant mentions. If you scroll down half a page you have almost the same sentence.
Reword TypeAlias intro. The root issue is that TypeAlias and type soft keyword are not the same. It is clear enough in the TypeAlias section, but you have to know to look there. I think is fair to hint at it in the introduction. If this is not direct enough, you could replace
Or marked with TypeAlias to make it explicit that this is a type alias, not a normal variable assignment
Or marked with TypeAlias to make it explicit that this is a type alias, not a normal variable assignment
Note this is separate and distinct from the keyword type. For more see, TypeAlias
📚 Documentation preview 📚: https://cpython-previews--114363.org.readthedocs.build/