Repository navigation
Move typing-related usage of PEP585 generics from typing docs to collections.abc #123523
Description
Documentation
As pointed out in #123521, currently we have typing-related usage of PEP585 generics (Generator, Callable, Coroutine, etc.) explained on typing page. However, those aliases are deprecated, and there's no backlink from their collections.abc counterparts.
So, currently all users of the recommended modern option (collections.abc generics) have no documentation regarding their use in typing context at hand. Worse, classes there don't even have their generic arguments listed - only the name:
class collections.abc.Generator
This clearly should be fixed. At minimum the following needs to hold:
collections.abcaliases have their generic arguments listed in the docs- All typing-related info from corresponding
typingdocs entries should be reachable fromcollections.abcdocs.
Upon some thinking I agree with @ZeroIntensity that moving all information to collections.abc and only retaining deprecation warning with a link in typing docs could be the most ergonomic option.
Linked PRs
- gh-123523: Rework typing documentation for generators and coroutines, and link to it from
collections.abcdocs #123544 - [3.13] gh-123523: Rework typing documentation for generators and coroutines, and link to it from
collections.abcdocs (GH-123544) #123790 - [3.12] gh-123523: Rework typing documentation for generators and coroutines, and link to it from
collections.abcdocs (#123544) #123792
Activity
ZeroIntensity commentedon Aug 31, 2024
@JelleZijlstra, as a typing expert, does this approach seem good to you?
AA-Turner commentedon Aug 31, 2024
As a user of collections generics, this would be quite useful, and seems appropriate now that Python 3.8 is nearing end-of-life. Happy to defer to others' views, though.
A
sterliakov commentedon Aug 31, 2024
I think +3 on the last comment is a good enough indicator - I'll grab this and open a PR soon.
gh-123523: Rework typing documentation for generators and coroutines,…
pythongh-123523: Rework typing documentation for generators and corou…
[3.12] pythongh-123523: Rework typing documentation for generators an…
[3.12] gh-123523: Rework typing documentation for generators and coro…
[3.13] gh-123523: Rework typing documentation for generators and coro…