python / python/cpython

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

Aberta
#123,583 3 comentários 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

docs topic-typing
Linguagem predominante
Python
Estrelas
77.2k
Forks
35.9k
Métricas de merge de PRs
Métricas de PR pendentes

Descrição

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.

Guia de contribuição

Abrir o guia de contribuição

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Direção de pesquisa

Comece revisando a documentação existente de collections.abc, as listagens de argumentos genéricos para os aliases typing obsoletos e as discussões relacionadas em #123544 e #123523. Adicione seções consistentes de Type parameters para os aliases genéricos relevantes, com seus argumentos e relacionamentos, e verifique se os usuários conseguem encontrar as informações a partir das entradas de collections.abc.

Escrita pelo modelo de indexação a partir do texto da issue.

Avaliação

Stack de tecnologia
python
Domínio
documentation
Tipo de issue
Documentação
Dificuldade
3/5
Tempo estimado
1-2 dias
Status de atividade
Estagnada
Clareza
Razoavelmente clara
Facilidade para iniciantes
35/100

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.