Skip to content

typing: Improve documentation of generic classes and aliases - #105369

Merged
AlexWaygood merged 6 commits into
python:mainfrom
AlexWaygood:deprecated-aliases
Jun 7, 2023
Merged

typing: Improve documentation of generic classes and aliases#105369
AlexWaygood merged 6 commits into
python:mainfrom
AlexWaygood:deprecated-aliases

Conversation

@AlexWaygood

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

Copy link
Copy Markdown
Member

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
Comment threadDoc/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]

@AlexWaygoodAlexWaygoodJun 6, 2023

Copy link
Copy Markdown
MemberAuthor

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

AlexWaygood commented Jun 6, 2023

Copy link
Copy Markdown
MemberAuthor

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
Comment threadDoc/library/typing.rst Outdated
Comment threadDoc/library/typing.rst Outdated
Comment threadDoc/library/typing.rst Outdated
Comment threadDoc/library/typing.rst Outdated
@AlexWaygood
AlexWaygood enabled auto-merge (squash) June 7, 2023 13:44
@AlexWaygood
AlexWaygood merged commit d63a7c3 into python:mainJun 7, 2023
@miss-islington

miss-islington commented Jun 7, 2023

Copy link
Copy Markdown
Contributor

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

@miss-islington

miss-islington commented Jun 7, 2023

Copy link
Copy Markdown
Contributor

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

bedevere-bot commented Jun 7, 2023

Copy link
Copy Markdown

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
@AlexWaygood
AlexWaygood 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

bedevere-bot commented Jun 7, 2023

Copy link
Copy Markdown

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