PEP 846: Docstrings for type aliases

[johnslavik]

I've just started the work on the PEP, hence a draft PR to book the number.

PR template checkboxes

Basic requirements (all PEP Types)

• Read and followed PEP 1 & PEP 12
• File created from the latest PEP template
• PEP has next available number, & set in filename (pep-NNNN.rst), PR title (PEP 123: <Title of PEP>) and PEP header
  • Tip: find the next available number with pepotron — run uvx pepotron next (or pipx install pepotron then pep next)
• Title clearly, accurately and concisely describes the content in 79 characters or less
• Core dev/PEP editor listed as Author or Sponsor, and formally confirmed their approval
• Author, Status (Draft), Type and Created headers filled out correctly
• PEP-Delegate, Topic, Requires and Replaces headers completed if appropriate
• Required sections included
  • Abstract (first section)
  • Copyright (last section; exact wording from template required)
• Code is well-formatted (PEP 7/PEP 8) and is in code blocks, with the right lexer names if non-Python
• PEP builds with no warnings, pre-commit checks pass and content displays as intended in the rendered HTML
• Authors/sponsor added to .github/CODEOWNERS for the PEP

Standards Track requirements

• PEP topic discussed in a suitable venue with general agreement that a PEP is appropriate
• Suggested sections included (unless not applicable)
  • Motivation
  • Specification
  • Rationale
  • Backwards Compatibility
  • Security Implications
  • How to Teach This
  • Reference Implementation
  • Rejected Ideas
  • Open Issues
  • Acknowledgements
  • Footnotes
  • Change History
• Python-Version set to valid (pre-beta) future Python version, if relevant
• Any project stated in the PEP as supporting/endorsing/benefiting from the PEP formally confirmed such
• Right before or after initial merging, PEP discussion thread created and linked to in Discussions-To and Post-History

[read-the-docs-community]

Documentation build overview

📚 pep-previews | 🛠️ Build #34430764 | 📁 Comparing fbd7b8a against latest (24419b9)

  🔍 Preview build  

5 files changed · + 1 added · ± 4 modified

+ Added

• pep-0846/index.html

± Modified

• index.html
• numerical/index.html
• pep-0000/index.html
• topic/typing/index.html

[JelleZijlstra]

Worth saying explicitly that there may be comments and blank lines between the type statement and its docstring?

[JelleZijlstra]

Why not?

[johnslavik]

Wasn't sure.

dataclasses.field(doc=...) is a good precedent, the API will be more convenient.

I've changed my mind, I'll add the new parameter.

[JelleZijlstra]

It's Topic: Typing, but there's nothing for type checkers to do. I can't really think of much type checkers could do with this PEP; maybe they could have some verbose diagnostics mode that shows alias docstrings, but that's not something the PEP should prescribe.

I guess this Topic implies that the Typing Council should opine on this PEP. And maybe there should be a line making it explicit that no changes in type checker behavior are expected.