https://github.com/python/cpython/commit/7e9c5772a88f9d39632d173de5fdbb223ca7923b
commit: 7e9c5772a88f9d39632d173de5fdbb223ca7923b
branch: 3.13
author: Miss Islington (bot) <31488909+miss-isling...@users.noreply.github.com>
committer: Yhg1s <tho...@python.org>
date: 2025-04-08T10:45:21+02:00
summary:
[3.13] gh-115684: Clarify datetime `replace` documentation (GH-116519) (#131676)
gh-115684: Clarify datetime `replace` documentation (GH-116519)
* Clarify datetime `replace` documentation
In GH-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 GH-115684.
* Include reviewer comments
Thanks Privat33r-dev for the comments!
---------
(cherry picked from commit d2d886215cf694d5f3e7f0cbd76507a96bac322b)
Co-authored-by: David Lowry-Duda <da...@lowryduda.com>
Co-authored-by: Paul Ganssle <1377457+pgans...@users.noreply.github.com>
files:
M Doc/library/datetime.rst
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 4c7d3cd119dd01..708258a3d8dc9e 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -666,8 +666,8 @@ Instance methods:
.. method:: date.replace(year=self.year, month=self.month, day=self.day)
- Return a date with the same value, except for those parameters given new
- values by whichever keyword arguments are specified.
+ Return a new :class:`date` object with the same values, but with specified
+ parameters updated.
Example::
@@ -676,8 +676,8 @@ Instance methods:
>>> d.replace(day=26)
datetime.date(2002, 12, 26)
- :class:`date` objects are also supported by generic function
- :func:`copy.replace`.
+ The generic function :func:`copy.replace` also supports :class:`date`
+ objects.
.. method:: date.timetuple()
@@ -1315,10 +1315,10 @@ Instance methods:
hour=self.hour, minute=self.minute, second=self.second,
microsecond=self.microsecond, \
tzinfo=self.tzinfo, *, fold=0)
- Return a datetime with the same attributes, except for those attributes
given
- new values by whichever keyword arguments are specified. Note that
- ``tzinfo=None`` can be specified to create a naive datetime from an aware
- datetime with no conversion of date and time data.
+ Return a new :class:`datetime` object with the same attributes, but with
+ specified parameters updated. Note that ``tzinfo=None`` can be specified to
+ create a naive datetime from an aware datetime with no conversion of date
+ and time data.
:class:`.datetime` objects are also supported by generic function
:func:`copy.replace`.
@@ -1893,10 +1893,10 @@ Instance methods:
.. method:: time.replace(hour=self.hour, minute=self.minute,
second=self.second, \
microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)
- Return a :class:`.time` with the same value, except for those attributes
given
- new values by whichever keyword arguments are specified. Note that
- ``tzinfo=None`` can be specified to create a naive :class:`.time` from an
- aware :class:`.time`, without conversion of the time data.
+ Return a new :class:`.time` with the same values, but with specified
+ parameters updated. Note that ``tzinfo=None`` can be specified to create a
+ naive :class:`.time` from an aware :class:`.time`, without conversion of the
+ time data.
:class:`.time` objects are also supported by generic function
:func:`copy.replace`.
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
