Skip to content
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

datetime.date.replace() description not clear enough #115684

Closed
HopedForLuck opened this issue Feb 19, 2024 · 1 comment · Fixed by #116519
Closed

datetime.date.replace() description not clear enough #115684

HopedForLuck opened this issue Feb 19, 2024 · 1 comment · Fixed by #116519
Labels
docs Documentation in the Doc dir

Comments

@HopedForLuck
Copy link

HopedForLuck commented Feb 19, 2024

Documentation

In documentation explanation to command date.replace() is not clear enough.
I'm not that experienced, so it's maybe look from junior perspective, but since documentation quite needed for beginers i think my opinion might be valuable.

In documentation description to this function says "Return a date with the same value, except for those parameters given new values by whichever keyword arguments are specified." and gives an examle:

--- from datetime import date
--- d = date(2002, 12, 31)
--- d.replace(day=26)
datetime.date(2002, 12, 26)

But it confused me, since it looks like you can change datetime object and as documentation says - datetime objects are immutable, so i had to check and of course you can't change variable like that, the only way that works if you create a new variable (for example: d2 = d.replace(day=26))

So i propose to make this part that there won't be any confusion for anyone by rephrasing it.
For example:

Return a new date object with the same value as initial, except for those parameters given new values by whichever keyword arguments are specified.

--- from datetime import date
--- d = date(2002, 12, 31)
--- d2 = d.replace(day=26)
--- d2
datetime.date(2002, 12, 26)

I haven't seen any tickets issued about this one, but i apologise if there is and i've missed it, or if i miss something in documentation itself.

Linked PRs

@HopedForLuck HopedForLuck added the docs Documentation in the Doc dir label Feb 19, 2024
davidlowryduda added a commit to davidlowryduda/cpython that referenced this issue Mar 8, 2024
In python#115684, HopedForLuck noted that `datetime.date.replace()`
documentation was confusing because it looked like it would be changing
immutable objects.

This documentation change specifies that the `replace()` methods in
`datetime` return new objects. This uses similar wording to the
documentation for `datetime.combine()`, which specifies that a new
datetime is returned. This is also similar to wording for
`string.replace()`, except `string.replace()` emphasizes that a "copy"
is returned.

Resolves python#115684.
davidlowryduda added a commit to davidlowryduda/cpython that referenced this issue Mar 8, 2024
In python#115684, HopedForLuck noted that `datetime.date.replace()`
documentation was confusing because it looked like it would be changing
immutable objects.

This documentation change specifies that the `replace()` methods in
`datetime` return new objects. This uses similar wording to the
documentation for `datetime.combine()`, which specifies that a new
datetime is returned. This is also similar to wording for
`string.replace()`, except `string.replace()` emphasizes that a "copy"
is returned.

Resolves python#115684.
davidlowryduda added a commit to davidlowryduda/cpython that referenced this issue Mar 8, 2024
In python#115684, HopedForLuck noted that `datetime.date.replace()`
documentation was confusing because it looked like it would be changing
immutable objects.

This documentation change specifies that the `replace()` methods in
`datetime` return new objects. This uses similar wording to the
documentation for `datetime.combine()`, which specifies that a new
datetime is returned. This is also similar to wording for
`string.replace()`, except `string.replace()` emphasizes that a "copy"
is returned.

Resolves python#115684.
@Privat33r-dev
Copy link
Contributor

Privat33r-dev commented Mar 14, 2024

Thank you for creating this issue, you are right that the documentation is not concise enough.

Rule of thumb for the future: usually if something is returning a value, it doesn't change the original element.

pganssle added a commit that referenced this issue Mar 24, 2025
* Clarify datetime `replace` documentation

In #115684, HopedForLuck noted that `datetime.date.replace()`
documentation was confusing because it looked like it would be changing
immutable objects.

This documentation change specifies that the `replace()` methods in
`datetime` return new objects. This uses similar wording to the
documentation for `datetime.combine()`, which specifies that a new
datetime is returned. This is also similar to wording for
`string.replace()`, except `string.replace()` emphasizes that a "copy"
is returned.

Resolves #115684.

* Include reviewer comments

Thanks Privat33r-dev for the comments!

---------

Co-authored-by: Paul Ganssle <1377457+pganssle@users.noreply.github.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Mar 24, 2025
…16519)

* Clarify datetime `replace` documentation

In pythonGH-115684, HopedForLuck noted that `datetime.date.replace()`
documentation was confusing because it looked like it would be changing
immutable objects.

This documentation change specifies that the `replace()` methods in
`datetime` return new objects. This uses similar wording to the
documentation for `datetime.combine()`, which specifies that a new
datetime is returned. This is also similar to wording for
`string.replace()`, except `string.replace()` emphasizes that a "copy"
is returned.

Resolves pythonGH-115684.

* Include reviewer comments

Thanks Privat33r-dev for the comments!

---------
(cherry picked from commit d2d8862)

Co-authored-by: David Lowry-Duda <david@lowryduda.com>
Co-authored-by: Paul Ganssle <1377457+pganssle@users.noreply.github.com>
davidlowryduda added a commit to davidlowryduda/cpython that referenced this issue Mar 24, 2025
…honGH-116519)

* Clarify datetime `replace` documentation

In pythonGH-115684, HopedForLuck noted that `datetime.date.replace()`
documentation was confusing because it looked like it would be changing
immutable objects.

This documentation change specifies that the `replace()` methods in
`datetime` return new objects. This uses similar wording to the
documentation for `datetime.combine()`, which specifies that a new
datetime is returned. This is also similar to wording for
`string.replace()`, except `string.replace()` emphasizes that a "copy"
is returned.

Resolves pythonGH-115684.

* Include reviewer comments

Thanks Privat33r-dev for the comments!

---------
(cherry picked from commit d2d8862)

Co-authored-by: David Lowry-Duda <david@lowryduda.com>
Co-authored-by: Paul Ganssle <1377457+pganssle@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
Development

Successfully merging a pull request may close this issue.

2 participants