Skip to content

Improve documentation for the copy module #134559

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ferdnyc opened this issue May 23, 2025 · 3 comments · May be fixed by #134695
Open

Improve documentation for the copy module #134559

ferdnyc opened this issue May 23, 2025 · 3 comments · May be fixed by #134695
Labels
docs Documentation in the Doc dir

Comments

@ferdnyc
Copy link
Contributor

ferdnyc commented May 23, 2025

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

@ferdnyc ferdnyc added the docs Documentation in the Doc dir label May 23, 2025
@AA-Turner
Copy link
Member

Do you have a suggested (re-)structure?

A

@tmlnv
Copy link
Contributor

tmlnv commented May 25, 2025

Hi!
I’ve addressed the first part of the issue by adding a .. versionadded:: 3.13 annotation to object.__replace__.
Because @ferdnyc hasn’t shared a restructuring proposal yet, I’ve left the rest of the documentation unchanged.

@ferdnyc
Copy link
Contributor Author

ferdnyc commented May 26, 2025

Jeez, c'mon guys... it's the weekend. 😀

But, here you go: My first stab at reorganized docs. Which got involved enough that I just decided to open a PR with the changes: #134695

miss-islington pushed a commit to miss-islington/cpython that referenced this issue May 26, 2025
…nGH-134672)

(cherry picked from commit 71290a6)

Co-authored-by: tmlnv <108088921+tmlnv@users.noreply.github.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this issue May 26, 2025
…nGH-134672)

(cherry picked from commit 71290a6)

Co-authored-by: tmlnv <108088921+tmlnv@users.noreply.github.com>
@AA-Turner AA-Turner changed the title copy.replace() is annotated as "versionadded: 3.13", but object.__replace__ isn't Improve documentation for the copy module May 26, 2025
AA-Turner pushed a commit that referenced this issue May 26, 2025
…34672) (#134699)

gh-134559: Add versionadded for ``object.__replace__()`` (GH-134672)
(cherry picked from commit 71290a6)

Co-authored-by: tmlnv <108088921+tmlnv@users.noreply.github.com>
AA-Turner pushed a commit that referenced this issue May 26, 2025
…34672) (#134700)

gh-134559: Add versionadded for ``object.__replace__()`` (GH-134672)
(cherry picked from commit 71290a6)

Co-authored-by: tmlnv <108088921+tmlnv@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir
Projects
Status: Todo
Development

Successfully merging a pull request may close this issue.

3 participants