Repository navigation
Closed
Labels
3.12only security fixesonly security fixesdocsDocumentation in the Doc dirDocumentation in the Doc dirtopic-typing
Description
We should document PEP-695 for Python 3.12 (issue #103763, PR #103764 for implementation). I am leaving docs out of the PR to avoid complicating an already huge PR with a tight deadline, but let's start thinking about what we need to document:
- New AST nodes in
ast.rst - Language reference should be updated to include the new grammar changes
- Language reference should be updated to reflect new scoping rules (https://docs.python.org/3.12/reference/executionmodel.html#naming-and-binding)
-
typing.rstshould list the PEP -
typing.rstshould mention thatTypeVargained aninfer_varianceargument and that it now supports lazily evaluated bounds/constraints - Examples of generics in
typing.rstshould use the new syntax -
typing.rstshould document the newTypeAliasType -
typing.TypeAliasshould be mentioned as deprecated (including in the deprecation timeline at the bottom oftyping.rst), and any examples of type aliases should be updated to use the new syntax - New opcodes need to be mentioned in
dis.rst.dis.disdocs should mention new contexts where nested code objects can appear. TheCALL_INTRINSIC_1and 2 opcodes should mention the new intrinsics.
Linked PRs
- gh-103921: Document PEP 695 #104642
- gh-103921: Rename "type" header in argparse docs #104654
- [3.12] gh-103921: Document PEP 695 (GH-104642) #104989
- [3.11] gh-103921: Improve typing documentation (GH-104642) #105007
- gh-103921: Minor PEP-695 fixes to the
astmodule docs #105093 - [3.12] gh-103921: Minor PEP-695 fixes to the
astmodule docs (GH-105093) #105101
Metadata
Metadata
Assignees
Labels
3.12only security fixesonly security fixesdocsDocumentation in the Doc dirDocumentation in the Doc dirtopic-typing
Activity
Fidget-Spinner commentedon Apr 27, 2023
Ideally we should also add the new builtin types to the list of stdtypes https://docs.python.org/3/library/stdtypes.html#type-annotation-types-generic-alias-union
IMO, they ought to belong there instead of
typing.rstastyping.rstis for the stdlib module.AlexWaygood commentedon Apr 27, 2023
I agree that we should make sure that PEP 695 is presented as the idiomatic, modern way of writing generic functions and classes. But I'd like us to make sure that the old-style way of doing things also continues to be well documented in
typing.rst, with plenty of examples. Many projects will continue to use the old way of defining generics for a long time after the release of Python 3.12, so that they'll be able to continue supporting older versions of Python. Unlike most other typing features, it will be impossible for us to backport most of PEP 695 totyping_extensions— we can't backport a syntax change.pythongh-103921: Rename "type" header in argparse docs
JelleZijlstra commentedon May 19, 2023
I'm not sure about this. The types still claim that their
__module__istyping, and they are accessible as e.g.typing.TypeVar. I feel they'd be more discoverable in thetypingdocs than the stdtypes page.gh-103921: Rename "type" header in argparse docs (#104654)
AlexWaygood commentedon May 19, 2023
I agree with @Fidget-Spinner.
types.GenericAliasandtypes.UnionTypeboth claim that their module istypes, but we only have "stub entries" for them intypes.rst; the extensive documentation for these classes is instdtypes.rst:Builtin types that have dedicated syntax should all be documented in the same place (
stdtypes.rst).JelleZijlstra commentedon May 19, 2023
I know, and I don't really like how the docs for GenericAlias and UnionType are organized; they'd probably also be cleaner if more of the docs were under
types.As a contrary example,
types.ModuleTypedocuments its attributes at https://docs.python.org/3.10/library/types.html#types.ModuleType, even though it claims its module is__builtins__.Concrete problems I see with documenting these types in stdtypes:
typing.rstabout them? We'll need to put some reference to the stdtypes description.typing.TypeVarelsewhere in the docs, but that would link to a stub description in the typing docs.My preference would be to keep the main documentation for TypeVar etc. in typing.rst, but add a note about them to https://docs.python.org/3.10/library/stdtypes.html#type-annotation-types-generic-alias-union.
AlexWaygood commentedon May 19, 2023
Fair enough, I've also thought this in the past.
I see the point about not wanting to break all cross-references to
TypeVar,ParamSpec, etc. -- it makes sense to leave those where they are.TypeAliasTypestill feels like it belongs next to the docs forUnionTypeandGenericAlias, to me. But, I agree that there's not perfect solution, and don't have a hugely strong opinion.Merge branch 'main' into gsallam/main
gh-103921: Document PEP 695 (#104642)
pythongh-103921: Document PEP 695 (pythonGH-104642)
[3.12] gh-103921: Document PEP 695 (GH-104642) (#104989)
AlexWaygood commentedon May 26, 2023
I think we're done here!
[3.11] pythongh-103921: Document PEP 695 (pythonGH-104642)
[3.11] gh-103921: Improve typing documentation (GH-104642) (#105007)
gh-103921: Minor PEP-695 fixes to the `ast` module docs (#105093)
pythongh-103921: Minor PEP-695 fixes to the `ast` module docs (python…
[3.12] gh-103921: Minor PEP-695 fixes to the `ast` module docs (GH-10…
Merge branch 'main' into superbadgetattro