Skip to content
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

Document PEP 695 #103921

Closed
9 tasks done
JelleZijlstra opened this issue Apr 27, 2023 · 7 comments
Closed
9 tasks done

Document PEP 695 #103921

JelleZijlstra opened this issue Apr 27, 2023 · 7 comments
Assignees
Labels
3.12 bugs and security fixes docs Documentation in the Doc dir topic-typing

Comments

@JelleZijlstra
Copy link
Member

JelleZijlstra commented Apr 27, 2023

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.rst should list the PEP
  • typing.rst should mention that TypeVar gained an infer_variance argument and that it now supports lazily evaluated bounds/constraints
  • Examples of generics in typing.rst should use the new syntax
  • typing.rst should document the new TypeAliasType
  • typing.TypeAlias should be mentioned as deprecated (including in the deprecation timeline at the bottom of typing.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.dis docs should mention new contexts where nested code objects can appear. The CALL_INTRINSIC_1 and 2 opcodes should mention the new intrinsics.

Linked PRs

@JelleZijlstra JelleZijlstra added docs Documentation in the Doc dir topic-typing 3.12 bugs and security fixes labels Apr 27, 2023
@JelleZijlstra JelleZijlstra self-assigned this Apr 27, 2023
@Fidget-Spinner
Copy link
Member

Fidget-Spinner commented 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.rst as typing.rst is for the stdlib module.

@AlexWaygood
Copy link
Member

AlexWaygood commented Apr 27, 2023

  • Examples of generics in typing.rst should use the new syntax

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 to typing_extensions — we can't backport a syntax change.

This was referenced May 12, 2023
JelleZijlstra added a commit to JelleZijlstra/cpython that referenced this issue May 19, 2023
This allows :keyword:`type` to link to docs for the new `type`
statement (being written in pythongh-104642) instead of to this header
in the argparse docs.
@JelleZijlstra
Copy link
Member Author

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.rst as typing.rst is for the stdlib module.

I'm not sure about this. The types still claim that their __module__ is typing, and they are accessible as e.g. typing.TypeVar. I feel they'd be more discoverable in the typing docs than the stdtypes page.

JelleZijlstra added a commit that referenced this issue May 19, 2023
This allows :keyword:`type` to link to docs for the new `type`
statement (being written in gh-104642) instead of to this header
in the argparse docs.
@AlexWaygood
Copy link
Member

AlexWaygood commented May 19, 2023

I agree with @Fidget-Spinner. types.GenericAlias and types.UnionType both claim that their module is types, but we only have "stub entries" for them in types.rst; the extensive documentation for these classes is in stdtypes.rst:

>>> type(list[int]).__module__
'types'
>>> type(int | str).__module__
'types'

Builtin types that have dedicated syntax should all be documented in the same place (stdtypes.rst).

@JelleZijlstra
Copy link
Member Author

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.ModuleType documents 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:

  • What would we put in typing.rst about them? We'll need to put some reference to the stdtypes description.
  • It's going to be natural to refer to e.g. :class:typing.TypeVar elsewhere 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
Copy link
Member

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.

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. TypeAliasType still feels like it belongs next to the docs for UnionType and GenericAlias, to me. But, I agree that there's not perfect solution, and don't have a hugely strong opinion.

carljm added a commit to gsallam/cpython_with_perfmap_apii that referenced this issue May 20, 2023
* main: (30 commits)
  pythongh-103987: fix several crashes in mmap module (python#103990)
  docs: fix wrong indentation causing rendering error in dis page (python#104661)
  pythongh-94906: Support multiple steps in math.nextafter (python#103881)
  pythongh-104472: Skip `test_subprocess.ProcessTestCase.test_empty_env` if ASAN is enabled (python#104667)
  pythongh-103839: Allow building Tkinter against Tcl 8.7 without external libtommath (pythonGH-103842)
  pythongh-85984: New additions and improvements to the tty library. (python#101832)
  pythongh-104659: Consolidate python examples in enum documentation (python#104665)
  pythongh-92248: Deprecate `type`, `choices`, `metavar` parameters of `argparse.BooleanOptionalAction` (python#103678)
  pythongh-104645: fix error handling in marshal tests (python#104646)
  pythongh-104600: Make type.__type_params__ writable (python#104634)
  pythongh-104602: Add additional test for listcomp with lambda (python#104639)
  pythongh-104640: Disallow walrus in comprehension within type scopes (python#104641)
  pythongh-103921: Rename "type" header in argparse docs (python#104654)
  Improve readability of `typing._ProtocolMeta.__instancecheck__` (python#104649)
  pythongh-96522: Fix deadlock in pty.spawn (python#96639)
  pythonGH-102818: Do not call `PyTraceBack_Here` in sys.settrace trampoline.  (pythonGH-104579)
  pythonGH-103545: Add macOS specific constants for ``os.setpriority`` to ``os`` (python#104606)
  pythongh-104623: Update macOS installer to SQLite 3.42.0 (pythonGH-104624)
  pythongh-104619: never leak comprehension locals to outer locals() (python#104637)
  pythongh-104602: ensure all cellvars are known up front (python#104603)
  ...
JelleZijlstra added a commit that referenced this issue May 26, 2023
miss-islington pushed a commit to miss-islington/cpython that referenced this issue May 26, 2023
(cherry picked from commit 060277d)

Co-authored-by: Jelle Zijlstra <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>
JelleZijlstra added a commit that referenced this issue May 26, 2023
(cherry picked from commit 060277d)

Co-authored-by: Jelle Zijlstra <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>
@AlexWaygood
Copy link
Member

I think we're done here!

JelleZijlstra pushed a commit that referenced this issue May 30, 2023
…5093) (#105101)

(cherry picked from commit c8c1e73)

Co-authored-by: Alex Waygood <[email protected]>
carljm added a commit to carljm/cpython that referenced this issue May 30, 2023
* main:
  CI: Temporarily skip paths with spaces to avoid error (python#105110)
  pythongh-105071: add missing versionadded directive (python#105097)
  pythongh-80064: Fix is_valid_wide_char() return type (python#105099)
  Small speedup for dataclass __eq__ and __repr__ (python#104904)
  pythongh-103921: Minor PEP-695 fixes to the `ast` module docs (python#105093)
  pythongh-105091: stable_abi.py: Remove "Unixy" check from --all on other platforms (pythonGH-105092)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
3.12 bugs and security fixes docs Documentation in the Doc dir topic-typing
Projects
None yet
Development

No branches or pull requests

3 participants