gh-123523: Rework typing documentation for generators and coroutines, and link to it from `collections.abc` docs by sterliakov · Pull Request #123544 · python/cpython

sterliakov · 2024-08-31T23:07:08Z

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).

Issue: Move typing-related usage of PEP585 generics from typing docs to collections.abc #123523

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

Similarly to `collections.abc` changes, this is not acceptable for now.

AlexWaygood

Looking much better now, thank you!

AlexWaygood · 2024-09-01T09:52:30Z

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".

…apping

…eference

…ndations

AlexWaygood

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)

… with `typing.Set`

miss-islington-app · 2024-09-06T16:41:10Z

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

…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 · 2024-09-06T16:41:19Z

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 · 2024-09-06T16:41:20Z

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

…d coroutines, and link to it from `collections.abc` docs (python#123544)

bedevere-app · 2024-09-06T16:58:23Z

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

…utines, and link to it from `collections.abc` docs (#123544) (#123792) Co-authored-by: Stanislav Terliakov <50529348+sterliakov@users.noreply.github.com>

…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>

sterliakov added 2 commits August 31, 2024 18:08

Move typing docs for deprecated aliases to collections.abc
412c358

Do the same with contextlib references
3a71312

sterliakov requested review from 1st1, AlexWaygood, JelleZijlstra and rhettinger as code owners August 31, 2024 23:07

bedevere-appBot mentioned this pull request Aug 31, 2024
Move typing-related usage of PEP585 generics from typing docs to collections.abc#123523
Closed

bedevere-appBot added docs Documentation in the Doc dir skip news awaiting review labels Aug 31, 2024

AlexWaygood reviewed Aug 31, 2024
View reviewed changes

Comment threadDoc/library/collections.abc.rst Outdated

AlexWaygood reviewed Aug 31, 2024
View reviewed changes

Comment threadDoc/library/collections.abc.rst Outdated

sterliakov added 5 commits September 1, 2024 02:25

Add a generators&coroutines section
c146cbd

Replace PEP695 parameters with Generic inheritance
8b6f65c

Remove type arguments for now
5aa430c

Revert "Do the same with contextlib references"
fb13736
Similarly to `collections.abc` changes, this is not acceptable for now.

Use double backticks
e7bd7b7

AlexWaygood reviewed Sep 1, 2024
View reviewed changes

AlexWaygood removed the request for review from 1st1 September 1, 2024 01:05

AlexWaygood changed the title ~~gh-123523: Move typing-related documentation for PEP585 aliases from typing to collections.abc~~gh-123523: Rework typing documentation for generators and coroutines, and link to it from collections.abc docsSep 1, 2024

Address review comments
5c513aa

AlexWaygood reviewed Sep 1, 2024
View reviewed changes

Comment threadDoc/library/collections.abc.rst Outdated

sterliakov added 2 commits September 1, 2024 15:54

s/details of/details on/g
c827599

Address other review comments
8bac826

AlexWaygood reviewed Sep 1, 2024
View reviewed changes

Comment threadDoc/library/collections.abc.rst Outdated
Comment threadDoc/library/collections.abc.rst Outdated

sterliakov added 3 commits September 1, 2024 17:12

Remove "This type may be used as follows" notes from List, Dict and M…
a65f256
…apping

Remove deprecated alias to typing.Callable from collections.abc r…
dfa8564
…eference

Add deprecation notice to typing.Callable and typing.Type recomme…
7de2e02
…ndations

AlexWaygood reviewed Sep 1, 2024
View reviewed changes

Comment threadDoc/library/collections.abc.rst Outdated

Use simple link
587d240

AlexWaygood approved these changes Sep 1, 2024
View reviewed changes

Comment threadDoc/library/typing.rst Outdated
Comment threadDoc/library/typing.rst Outdated

bedevere-appBot added awaiting merge and removed awaiting review labels Sep 1, 2024

AlexWaygood added needs backport to 3.12 only security fixes needs backport to 3.13 bugs and security fixes labels Sep 1, 2024

Reference modern collections.abc aliases
e35d682

sterliakov mentioned this pull request Sep 1, 2024
List generic arguments for collections.abc base classes in documentation #123583
Open

AlexWaygood reviewed Sep 1, 2024
View reviewed changes

Comment threadDoc/library/typing.rst Outdated

Use fully qualified name for collections.abc.Set to avoid confusion…
fc16d76
… with `typing.Set`

picnixz reviewed Sep 3, 2024
View reviewed changes

Comment threadDoc/library/collections.abc.rst
Comment threadDoc/library/typing.rst

s/Refer to/See
24ff30e

AlexWaygood reviewed Sep 3, 2024
View reviewed changes

Comment threadDoc/library/typing.rst Outdated

Disambiguate typing.Set and collections.abc.Set
e63c976

rhettinger removed their request for review September 5, 2024 03:16

AlexWaygood merged commit 56e4a41 into python:mainSep 6, 2024

bedevere-appBot removed the awaiting merge label Sep 6, 2024

miss-islington-appBot assigned AlexWaygood Sep 6, 2024

bedevere-appBot 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
[3.12]pythongh-123523: Rework typing documentation for generators an…
b1d4d51
…d coroutines, and link to it from `collections.abc` docs (python#123544)

bedevere-appBot removed the needs backport to 3.12 only security fixes label Sep 6, 2024

AA-Turner mentioned this pull request Oct 19, 2024
Use the latest Sphinx version #125722
Closed

Uh oh!

Uh oh!

Conversation

sterliakov commented Aug 31, 2024• edited by github-actions BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AlexWaygood left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AlexWaygood commented Sep 1, 2024

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AlexWaygood left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

miss-islington-appBot commented Sep 6, 2024

Uh oh!

miss-islington-appBot commented Sep 6, 2024

Uh oh!

bedevere-appBot commented Sep 6, 2024

Uh oh!

bedevere-appBot commented Sep 6, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

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

AlexWaygood left a comment •
edited
Loading