mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-04 17:08:35 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

gh-115684: Clarify datetime replace documentation (#116519)

Browse source 
* 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>
This commit is contained in:
David Lowry-Duda 2025-03-24 11:33:16 -04:00 • committed by GitHub
parent d716ea34cb
commit d2d886215c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 12 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

24
Doc/library/datetime.rst
View file

@ -699,8 +699,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::
@ -709,8 +709,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()
@ -1348,10 +1348,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`.
@ -1942,10 +1942,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`.