-
-
Notifications
You must be signed in to change notification settings - Fork 31.4k
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
Labels
docs
Documentation in the Doc dir
Comments
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.
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
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:
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.
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
replace
documentation #116519replace
documentation (GH-116519) #131676replace
documentation (GH-116519) #131683replace
documentation (GH-116519) #131694The text was updated successfully, but these errors were encountered: