From 0a18ea56e8d075101c30b0b420f54ef00f05bdfc Mon Sep 17 00:00:00 2001 From: David Lowry-Duda Date: Fri, 8 Mar 2024 16:06:24 -0500 Subject: [PATCH 1/2] 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. --- Doc/library/datetime.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 1905c9e1ca755d..dd20816ca3d466 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -646,8 +646,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 date with the same values, except with new values for + those parameters given by whichever keyword arguments are specified. Example:: @@ -1273,10 +1273,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 datetime with the same attributes, except with new attributes + for those parameters given 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. :class:`.datetime` objects are also supported by generic function :func:`copy.replace`. @@ -1851,10 +1851,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, except with new values for + those attributes given 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. :class:`.time` objects are also supported by generic function :func:`copy.replace`. From c278f0aa9ba477ea4797367e8c0bc27ba9446fd0 Mon Sep 17 00:00:00 2001 From: David Lowry-Duda Date: Fri, 15 Mar 2024 14:05:06 -0400 Subject: [PATCH 2/2] Include reviewer comments Thanks Privat33r-dev for the comments! --- Doc/library/datetime.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index dd20816ca3d466..571cef9b7331b3 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -646,8 +646,8 @@ Instance methods: .. method:: date.replace(year=self.year, month=self.month, day=self.day) - Return a new date with the same values, except with new values for - those parameters given by whichever keyword arguments are specified. + Return a new :class:`date` object with the same values, but with specified + parameters updated. Example:: @@ -656,8 +656,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() @@ -1273,10 +1273,10 @@ Instance methods: hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, \ tzinfo=self.tzinfo, *, fold=0) - Return a new datetime with the same attributes, except with new attributes - for those parameters given 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`. @@ -1851,10 +1851,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 new :class:`.time` with the same values, except with new values for - those attributes given 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`.