◐ Shell
reader mode source ↗
Skip to content

gh-123523: Rework typing documentation for generators and coroutines, and link to it from collections.abc docs#123544

Merged
AlexWaygood merged 18 commits into
python:mainfrom
sterliakov:docs/gh-123523-pep585-typing-docs
Sep 6, 2024
Merged

gh-123523: Rework typing documentation for generators and coroutines, and link to it from collections.abc docs#123544
AlexWaygood merged 18 commits into
python:mainfrom
sterliakov:docs/gh-123523-pep585-typing-docs

Conversation

@sterliakov

@sterliakov sterliakov commented Aug 31, 2024 •
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Contributor

Fixes #123523.

Aliases from typing to collections.abc and contextlib modules are deprecated for a long time, and typing-related documentation should be easily reachable from the modern pages.

This PR moves all non-trivial descriptions between these pages and lists generic arguments for these aliases.

I'm using PEP695 syntax for these classes - it doesn't seem right to document them as inheriting from Generic, since they do not in fact (they define __class_getitem__ directly).

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

@bedevere-app bedevere-app Bot mentioned this pull request Aug 31, 2024
Closed
@bedevere-app bedevere-app Bot added docs Documentation in the Doc dir skip news awaiting review labels Aug 31, 2024
AlexWaygood
AlexWaygood reviewed Sep 1, 2024
View reviewed changes

@AlexWaygood AlexWaygood left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Hide comment

Looking much better now, thank you!

@AlexWaygood AlexWaygood removed the request for review from 1st1 September 1, 2024 01:05
@AlexWaygood AlexWaygood changed the title gh-123523: Move typing-related documentation for PEP585 aliases from typing to collections.abc Sep 1, 2024
@AlexWaygood

AlexWaygood commented Sep 1, 2024

Copy link
Copy Markdown
Member

You use the phrase "Refer to [this other documentation]" quite a lot -- I'd probably just use "See [this other documentation]" instead, as it's slightly shorter. But not strong opinion; I'm also okay with "Refer to".

31 hidden items Load more…
AlexWaygood
AlexWaygood approved these changes Sep 1, 2024
View reviewed changes

@AlexWaygood AlexWaygood left a comment •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Hide comment

LGTM. I'll leave it open for a few days in case anybody else wants to chime in (ping me in a week if there are no comments from anybody else and I haven't merged it by then)

@AlexWaygood AlexWaygood added needs backport to 3.12 only security fixes needs backport to 3.13 bugs and security fixes labels Sep 1, 2024
@sterliakov sterliakov mentioned this pull request Sep 1, 2024
Open
@rhettinger rhettinger removed their request for review September 5, 2024 03:16
@AlexWaygood AlexWaygood merged commit 56e4a41 into python:main Sep 6, 2024
@miss-islington-app

miss-islington-app Bot commented Sep 6, 2024

Copy link
Copy Markdown

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Sep 6, 2024
@sterliakov @miss-islington
pythongh-123523: Rework typing documentation for generators and corou… …
6597ba0 
…tines, and link to it from `collections.abc` docs (pythonGH-123544)

(cherry picked from commit 56e4a41)

Co-authored-by: Stanislav Terliakov <50529348+sterliakov@users.noreply.github.com>
@miss-islington-app

miss-islington-app Bot commented Sep 6, 2024

Copy link
Copy Markdown

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

cherry_picker 56e4a417ce170e5c538ce9aafccf3333e7bf7492 3.12

@bedevere-app

bedevere-app Bot commented Sep 6, 2024

Copy link
Copy Markdown

GH-123790 is a backport of this pull request to the 3.13 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.13 bugs and security fixes label Sep 6, 2024
AlexWaygood pushed a commit to AlexWaygood/cpython that referenced this pull request Sep 6, 2024
@sterliakov @AlexWaygood
[3.12] pythongh-123523: Rework typing documentation for generators an… …
b1d4d51 
…d coroutines, and link to it from `collections.abc` docs (python#123544)
@bedevere-app

bedevere-app Bot commented Sep 6, 2024

Copy link
Copy Markdown

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

@bedevere-app bedevere-app Bot removed the needs backport to 3.12 only security fixes label Sep 6, 2024
AlexWaygood added a commit that referenced this pull request Sep 6, 2024
@AlexWaygood @sterliakov
[3.12] gh-123523: Rework typing documentation for generators and coro… …
7e51091 
…utines, and link to it from `collections.abc` docs (#123544) (#123792)

Co-authored-by: Stanislav Terliakov <50529348+sterliakov@users.noreply.github.com>
Yhg1s pushed a commit that referenced this pull request Sep 6, 2024
@miss-islington @sterliakov
[3.13] gh-123523: Rework typing documentation for generators and coro… …
e62cb77 
…utines, and link to it from `collections.abc` docs (GH-123544) (#123790)

gh-123523: Rework typing documentation for generators and coroutines, and link to it from `collections.abc` docs (GH-123544)
(cherry picked from commit 56e4a41)

Co-authored-by: Stanislav Terliakov <50529348+sterliakov@users.noreply.github.com>
@AA-Turner AA-Turner mentioned this pull request Oct 19, 2024
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@AA-Turner AA-Turner AA-Turner left review comments

@picnixz picnixz picnixz left review comments

@AlexWaygood AlexWaygood AlexWaygood approved these changes

@JelleZijlstra JelleZijlstra Awaiting requested review from JelleZijlstra JelleZijlstra is a code owner

Assignees

@AlexWaygood AlexWaygood

Labels

docs skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Move typing-related usage of PEP585 generics from typing docs to collections.abc

4 participants

@sterliakov @AlexWaygood @AA-Turner @picnixz