python / python/cpython

List generic arguments for `collections.abc` base classes in documentation

Open
#123,583 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

docs topic-typing
Dominant language
Python
Stars
77.2k
Forks
35.9k
PR merge metrics
PR metrics pending

Description

Documentation

When #123544 lands, we'll have PEP585-related documentation spread even further than before. Deprecated aliases in typing correctly list the generic arguments, but are otherwise undocumented - all such entries boil down to "deprecated in favour of collections.abc.X".

Several relevant changes were discussed along #123523.

There's no direct way for a user to find generic parameters of collections.abc.Generator - they are listed for typing.Generator and in "annotating generators and coroutines" section in typing docs (the latter linked from collections.abc.Generator, though).

I'm certain that generic arguments represent an essential part of class' "signature" - basic amount of information we need to see to use it somehow.

However, collections.abc is not really a type-hinting module, hence providing those signatures there directly can add too much cognitive load.

As of now, my best suggestion is to introduce "Type parameters" section for each generic alias there, like this:

.. class:: Mapping
           MutableMapping

   ABCs for read-only and mutable :term:`mappings <mapping>`.

   Type arguments:

   * ``Mapping[KT, VT_co](Collection[KT])``
   * ``MutableMapping[KT, VT](Mapping[KT, VT])``

cc @AA-Turner and @AlexWaygood - we started this discussion in the PR above.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the existing collections.abc documentation, the generic-argument listings for deprecated typing aliases, and the related discussions in #123544 and #123523. Add consistent Type parameters sections for the relevant generic aliases, with their arguments and relationships, and verify that users can find the information from the collections.abc entries.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.