python / python/cpython

Improve documentation for the ``copy`` module

Offen
#134,559 3 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

docs
Vorherrschende Sprache
Python
Sterne
77.2k
Forks
35.9k
PR-Merge-Kennzahlen
PR-Kennzahlen ausstehend

Beschreibung

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

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginnen Sie mit der Dokumentationsseite des Moduls copy und vergleichen Sie die Abschnitte zu copy.replace() und object.replace, einschließlich ihrer Versionshinweise. Prüfen Sie die verknüpften PRs gh-134672, gh-134695, gh-134699 und gh-134700; als abgeschlossen gilt die Arbeit, wenn eine abgestimmte Dokumentationsstruktur und eine konsistente Behandlung der Python 3.13-Anmerkungen erreicht wurden.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Muss geklärt werden
Anfängerfreundlichkeit
20/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.