Skip to content

typing: Improve documentation of generic classes and aliases#105369

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.

Sign up for GitHub

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

Jump to bottom
Merged
AlexWaygood merged 6 commits into from
Jun 7, 2023
Merged

typing: Improve documentation of generic classes and aliases #105369

AlexWaygood merged 6 commits into from
Jun 7, 2023

Conversation

@AlexWaygood
Copy link
Member

@AlexWaygoodAlexWaygood commented Jun 6, 2023•
edited by github-actions bot
Loading

The documentation for typing.Dict currently describes the alias as:

A generic version of :class:dict.

In 2023, this is pretty misleading: it implies that dict is not generic, and that you have to use typing.Dict if you want to supply type parameters. There are similar issues across the typing documentation for the various aliases that were deprecated as part of PEP-585.

This PR also makes a few related edits to the docs for generic classes, which look like they still have some pre-PEP-585 language in them.

📚 Documentation preview 📚: https://cpython-previews--105369.org.readthedocs.build/

AlexWaygood
AlexWaygood commented Jun 6, 2023
View reviewed changes
Doc/library/typing.rst Outdated
Comment on lines 322 to 323
def second(l: Sequence[U]) -> U: # Function is generic around the TypeVar "U"
return l[1]
Copy link
MemberAuthor

@AlexWaygoodAlexWaygoodJun 6, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I figured it was slightly confusing to have two functions named first in two adjacent code examples

@AlexWaygoodAlexWaygood changed the title typing: Improve documentation of generic classestyping: Improve documentation of generic classes and aliasesJun 6, 2023
@AlexWaygood
Copy link
MemberAuthor

AlexWaygood commented Jun 6, 2023

Docs preview: https://cpython-previews--105369.org.readthedocs.build/en/105369/library/typing.html#module-typing

JelleZijlstra
JelleZijlstra reviewed Jun 7, 2023
View reviewed changes
@AlexWaygoodAlexWaygood enabled auto-merge (squash) June 7, 2023 13:44
@AlexWaygoodAlexWaygood merged commit d63a7c3 into python:mainJun 7, 2023
@miss-islington
Copy link
Contributor

miss-islington commented Jun 7, 2023

Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

@miss-islington
Copy link
Contributor

miss-islington commented Jun 7, 2023

Sorry, @AlexWaygood, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker d63a7c3694d5c4484fcaa01c33590b1d4bc2559e 3.11

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jun 7, 2023
@AlexWaygood@miss-islington
typing: Improve documentation of generic classes and aliases (pythonG…
fc339d7
…H-105369) (cherry picked from commit d63a7c3) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
@bedevere-bot
Copy link

bedevere-bot commented Jun 7, 2023

GH-105453 is a backport of this pull request to the 3.12 branch.

@bedevere-botbedevere-bot removed the needs backport to 3.12 only security fixes label Jun 7, 2023
@AlexWaygoodAlexWaygood deleted the deprecated-aliases branch June 7, 2023 14:03
AlexWaygood added a commit to AlexWaygood/cpython that referenced this pull request Jun 7, 2023
@AlexWaygood
[3.11] typing: Improve documentation of generic classes and aliases (p…
32b0683
…ython#105369)
@bedevere-bot
Copy link

bedevere-bot commented Jun 7, 2023

GH-105454 is a backport of this pull request to the 3.11 branch.

@bedevere-botbedevere-bot removed the needs backport to 3.11 only security fixes label Jun 7, 2023
AlexWaygood added a commit that referenced this pull request Jun 7, 2023
@miss-islington@AlexWaygood
[3.12] typing: Improve documentation of generic classes and aliases (G…
9a7c4a5
…H-105369) (#105453) typing: Improve documentation of generic classes and aliases (GH-105369) (cherry picked from commit d63a7c3) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
JelleZijlstra pushed a commit that referenced this pull request Jun 7, 2023
@AlexWaygood
[3.11] typing: Improve documentation of generic classes and aliases (#…
ccc9717
…105369) (#105454)
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@JelleZijlstraJelleZijlstraJelleZijlstra approved these changes

@gvanrossumgvanrossumAwaiting requested review from gvanrossum

@Fidget-SpinnerFidget-SpinnerAwaiting requested review from Fidget-Spinner

Assignees

@AlexWaygoodAlexWaygood

Labels

docsDocumentation in the Doc dirskip issueskip newstopic-typing

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@AlexWaygood@miss-islington@bedevere-bot@JelleZijlstra