Skip to content

Add __replace__ protocol support to timedelta #135195

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mpkocher opened this issue Jun 5, 2025 · 5 comments
Closed

Add __replace__ protocol support to timedelta #135195

mpkocher opened this issue Jun 5, 2025 · 5 comments
Labels
extension-modules C modules in the Modules dir pending The issue will be closed if no feedback is provided stdlib Python modules in the Lib dir type-feature A feature request or enhancement

Comments

@mpkocher
Copy link
Contributor

mpkocher commented Jun 5, 2025

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

@mpkocher mpkocher added the type-feature A feature request or enhancement label Jun 5, 2025
@vstinner
Copy link
Member

vstinner commented Jun 6, 2025

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

@StanFromIreland
Copy link
Contributor

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

@serhiy-storchaka
Copy link
Member

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.

@picnixz picnixz added stdlib Python modules in the Lib dir extension-modules C modules in the Modules dir pending The issue will be closed if no feedback is provided labels Jun 7, 2025
@vstinner
Copy link
Member

vstinner commented Jun 9, 2025

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

@vstinner vstinner closed this as not planned Won't fix, can't repro, duplicate, stale Jun 9, 2025
@mpkocher
Copy link
Contributor Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
extension-modules C modules in the Modules dir pending The issue will be closed if no feedback is provided stdlib Python modules in the Lib dir type-feature A feature request or enhancement
Projects
Development

No branches or pull requests

5 participants