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.abc aliases have their generic arguments listed in the docs
• All typing-related info from corresponding typing docs entries should be reachable from collections.abc docs.

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.abc docs #123544
• [3.13] gh-123523: Rework typing documentation for generators and coroutines, and link to it from collections.abc docs (GH-123544) #123790
• [3.12] gh-123523: Rework typing documentation for generators and coroutines, and link to it from collections.abc docs (#123544) #123792