python / python/cpython

Improve documentation for the ``copy`` module

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

Ninguém assumiu esta issue ainda.

docs
Linguagem predominante
Python
Estrelas
77.2k
Forks
36k
Métricas de merge de PRs
Métricas de PR pendentes

Descrição

Documentation

In the copy module documentation, the function copy.replace() has a .. versionadded:: annotation marking it as new in Python 3.13.

But the related object.__replace__ dunder method — which is documented muuuuuch farther down the page, near the very end — has no such annotation.

IMHO the two are too far apart and separated by too much completely unrelated documentation, for the annotation from copy.replace() to be implicitly applicable to object.__replace__ as well.

Module-level organization of content

To be perfectly honest, I'm not sure it makes sense for copy.replace() to eventually be documented so far from where it's initially introduced. Especially considering how brief that documentation actually is, the separation may do more harm than good.

No other module in the "Data Types" section starts with an "Interface summary:" like the one in the copy documentation. The most similar doc is the enum module's, which has a §Module Contents at the start. But there inline version annotations are skipped to keep the TOC concise, instead they're collected down below the list itself. Relevant annotations are also included in the detailed documentation sections that follow.

The organization of the copy docs is sort of... well, there's much less organization there, than in the documentation for other modules. (Probably attributable to both the age and extremely short length of the copy documentation.)

Linked PRs
  • gh-134672
  • gh-134695
  • gh-134699
  • gh-134700

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 pela página de documentação do módulo copy e compare as seções copy.replace() e object.replace, incluindo suas anotações de versão. Revise os PRs vinculados gh-134672, gh-134695, gh-134699 e gh-134700; a tarefa estará concluída quando houver uma organização acordada da documentação e um tratamento consistente das anotações do Python 3.13.

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
5/5
Tempo estimado
Mais de uma semana
Status de atividade
Estagnada
Clareza
Precisa de esclarecimento
Facilidade para iniciantes
20/100

Receba novas issues na sua caixa de entrada

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