Add __replace__ protocol support to timedelta

[mpkocher]

Feature or enhancement

Proposal:

Requirements:

• Add __replace__ support for timedelta
• Add .replace() to timedelta to be consistent with date and datetime

Currently, both date and datetime have a .replace() method and supports the __replace__ protocol

For unclear reasons, timedelta doesn't follow suit.

In [1]: from datetime import datetime, date, timedelta

In [2]: d = datetime.now()

In [3]: d.replace(day=1)
Out[3]: datetime.datetime(2025, 6, 1, 16, 50, 54, 282957)

In [4]: import copy

In [6]: copy.replace(d, second=1)
Out[6]: datetime.datetime(2025, 6, 5, 16, 50, 1, 282957)

In [7]: d = date.today()

In [8]: d.replace(day=1)
Out[8]: datetime.date(2025, 6, 1)

In [10]: copy.replace(d, day=1)
Out[10]: datetime.date(2025, 6, 1)

In [11]: t = timedelta(seconds=100)

In [12]: copy.replace(t, second=1)
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
Cell In[12], line 1
----> 1 copy.replace(t, second=1)

File ~/miniconda3/envs/core-313/lib/python3.13/copy.py:305, in replace(obj, **changes)
    303 func = getattr(cls, '__replace__', None)
    304 if func is None:
--> 305     raise TypeError(f"replace() does not support {cls.__name__} objects")
    306 return func(obj, **changes)

TypeError: replace() does not support timedelta objects
# Add a code block here, if required

Has this already been discussed elsewhere?

No response given

Links to previous discussion of this feature:

No response

[vstinner]

It makes sense to add a replace() method and support the __replace__() protocol for datetime.timedelta.

[StanFromIreland]

I can implement, unless you want to @mpkocher ? And, @pganssle , any reasons to not implement?

[serhiy-storchaka]

It was not implemented because ambiguous semantic.

Let you have td = timedelta(minutes=5, seconds=102).

>>> from datetime import *
>>> td = timedelta(minutes=5, seconds=102)
>>> td
datetime.timedelta(seconds=402)

What should td.replace(seconds=250) return -- timedelta(minutes=5, seconds=250) or timedelta(seconds=250)? What should td.replace(minutes=3) return -- timedelta(minutes=3, seconds=102), timedelta(minutes=3, seconds=42) or timedelta(seconds=180)? If the last option is the answer in both cases, how does it differ from just using the timedelta constructor? And I haven't even touched on the issue of days and microseconds, which complicates things even more.

[vstinner]

I agree with @serhiy-storchaka. Let's close this issue.

[mpkocher]

For context, my use case was for cleaning up the formatting time deltas to not have microsecond resolution when printing from a commandline tool. This either required truncating when the date time snapshots with t0.replace(microsecond=0), or doing timedelta(seconds=round(dt.total_seconds())) just to get the desired output formatting. It seemed like using __replace__ on timedelta would be a good use for this case.

It was not implemented because ambiguous semantic.

The public interface to timedelta is a bit of a peculiar design choice of having .days, .seconds, .microseconds and total_seconds().

I believe this design choice is the fundamental friction point when trying to add __replace__ semantics to timedelta. It looks like this is the same core challenge when trying to adopt pattern matching semantics to timedelta. #123882

There's not a "normalized" public interface that is allows access to normalized units of time (e.g., days, hours, minutes, seconds, microseconds). In the current API design, I suspect people often misuse .seconds when they really mean .total_seconds(). Another friction point is negative values are treated can be quite counterintuitive. While this is documented, it's still a bit of thorny interface. A "normalized" units version would perhaps be more intuitive.

Given the backwards incompatibility constraints, I'm not sure there's a path forward on this.

[vstinner]

You can remove microseconds this way:

>>> import datetime
>>> td=datetime.timedelta(weeks=10, seconds=3600, microseconds=123_456)
>>> datetime.timedelta(days=td.days, seconds=td.seconds)  # remove microseconds
datetime.timedelta(days=70, seconds=3600)