python / python/cpython

Improve documentation for the ``copy`` module

Ouverte
#134,559 3 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

docs
Langage dominant
Python
Étoiles
77.2k
Forks
35.9k
Métriques de merge des PR
Métriques de PR en attente

Description

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

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Commencez par la page de documentation du module copy et comparez les sections copy.replace() et object.replace, y compris leurs annotations de version. Examinez les PRs associés gh-134672, gh-134695, gh-134699 et gh-134700 ; le travail sera considéré comme terminé lorsqu’une organisation de la documentation et un traitement cohérent des annotations de Python 3.13 auront été convenus.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
python
Domaine
documentation
Type d'issue
Documentation
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
À l'abandon
Clarté
À clarifier
Accessibilité débutants
20/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.