datetime.date.replace() description not clear enough

[HopedForLuck]

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:

--- from datetime import date
--- d = date(2002, 12, 31)
--- d.replace(day=26)
datetime.date(2002, 12, 26)

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.

--- from datetime import date
--- d = date(2002, 12, 31)
--- d2 = d.replace(day=26)
--- d2
datetime.date(2002, 12, 26)

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

• gh-116519

[Privat33r-dev]

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.