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
typing module docs: keep text, add subsections #85151
Comments
The typing module documentation page has a very long section "Classes, functions, and decorators" (https://docs.python.org/3/library/typing.html#classes-functions-and-decorators) that should be split in subsections. The ordering of the entries seems haphazard: it's not alphabetical. Its grouped according to invisible categories. The categories appear as comments in the source code of typing.py: the
|
Would you care to submit a PR? |
Thanks, I am happy to submit a PR. Before I do, I'd like to discuss the subsection titles, starting from the arrangement in typing.__all__: # Special typing constructs (source comment is: "Super-special typing primitives") In this section I propose we add:
# ABCs (from collections.abc) [Keep this title] # Concrete collection types [keep this title]
# Protocols (source comment is "Structural checks, a.k.a. protocols.") # Functions and decorators (source comment is "One-off things.")
There are also the IO and re types which could have their own subsections. Looking forward for feeback on this. Thanks! |
Sorry, there was an editing mistake above. Where I wrote:
I meant to write:
|
This is my proposal for sections to replace the existing "Classes, functions, and decorators" section. The names are sorted within each section. # Special typing primitives # Generic ABCs # Generic Concrete Collections # Structural checks, a.k.a. protocols. # Functions and decorators # Aliases and constants |
Reviewers, besides adding section titles and reordering the entries, I made only these changes to the text:
|
This organization makes good sense to me. Hopefully, we can get Guido and Ivan to take a look at it. |
FWIW I like Guido's suggestion in the PR, I would rather use "importance order" than alphabetical order. |
I have incorporated Guido's suggestions and added additional subsections to make it easier to navigate the page. I also added notes that fix the issue https://bugs.python.org/issue40978 — "Document that typing.SupportsXXX protocols are runtime checkable" |
Thank you so much for your hard work and flexibility! The chapter is in much better shape now. |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: