[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 d2d8862)

Co-authored-by: David Lowry-Duda <[email protected]>
Co-authored-by: Paul Ganssle <[email protected]>

Author: 3 people

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`.