Rename, alias, and deprecate timedelta part attributes

Ideas
1

Hi everyone :waving_hand:

I’d like to propose a solution to a problem that I keep running into regularly at work. The names of the attributes of datetime.timedelta objects, .days, .seconds, and .microseconds, are very easily mistaken as representation of the full accumulated value of the timedelta object. However, the only exposed way of accessing that is through the .total_seconds() method. Instead, these attributes rather represents broken apart pieces of a timedelta at different resolutions, that when added together make up the full value.

This issue has surfaced countless of times in code review, and I bet we have lingering production bugs that are due to this, yet to be discovered. This is also backed up by the fact that the .seconds attribute has a special warning call-out in the documentation that informs of this common mixup.

To remedy this issue, I would like to propose a long-term plan of phasing these three attributes out, in preference of a set of new and more verbose names. The attributes would be renamed like below (though feel free to suggest other naming schemes):

  • timedelta.days → timedelta.part_days
  • timedelta.seconds → timedelta.part_seconds
  • timedelta.microseconds → timedelta.part_microseconds

The idea of this renaming is that the new names in a much better way are communicating that they are not the full timedelta value, but only a part of it.

In order not to break any existing code, and give plenty of time for users to migrate, the old names will be considered deprecated aliases of the new ones. The implementation could for example be done as @property methods that return the underlying values.

I suggest marking the alias properties with @deprecated("Superseded by .part_$attribute", category=None) for an initial period of 5 years, until all supported Python versions have the new attributes, and then after that with @deprecated("Superseded by .part_$attribute") to give a runtime warning for another 5 years before the existing attributes can be finally scheduled for removal.

Marking the attributes with the non-warning @deprecated() decorator initially will allow IDEs and type checker to yield diagnoses for usages of the attributes, encouraging users to migrate to the newly proposed ones, well ahead of time of their planned removal.

Edit: and also linters can be given functionality for giving diagnoses during this initial period.

I believe this will make Python friendlier to newcomers and long-timers alike, as this is a quirk that’s very easy to miss, a common issue, and not trivial to solve with something like linting, as the attributes also have legitimate uses.

7 Likes
2

We could also completely get rid of these attributes. They are equivalent to the following expressions:

td.days == td // timedelta(days=1)
td.seconds == (td // timedelta(seconds=1)) % (24 * 60 * 60)
td.microseconds == (td // timedelta(microseconds=1)) % 10**6

I can’t recall a single time when they were needed. Having only days, seconds and microseconds is arbitrary – this is just a leaked implementation detail on 32-bit Python 2. There are no weeks, hours, minutes and milliseconds.

9 Likes
3

In mxDateTime, which predates the stdlib datetime module, I used these attributes:

To make life easier, the instances also provide a more direct interface to their stored values (these are all read-only):

.day, .hour, .minute, .second

Return the indicated values in their standard ranges. The values are negative for negative time deltas.

.days, .hours, .minutes, .seconds

Return the internal value of the object expressed as float in the resp. units, e.g. TimeDelta(12,00,00).days == 0.5.

(https://www.egenix.com/products/python/mxBase/mxDateTime/doc/#_Toc353894686)

I used the plural forms a lot in my code, since you often need access time deltas in different scales.

The singular forms provided access to the time delta value in broken down form, which were also available via the .tuple() method. You mostly use those when interpreting a time delta as a time value (time of day, as we know it, is simply a time delta against midnight of the current day).

Since the datetime module does have a separate time object, I don’t think the same usage pattern applies and so +1 on deprecating those attributes.

4 Likes
4

I also find the reasons for deprecation rational.

I’d like to propose that timedelta shall provide a method to export a 5-tuple (days, hours, mins, secs, microsecs). Having one complete set of numbers removes the ambiguity of the current API where there are three separate properties.

Timedelta already has the code to compute these 5 numbers, because it needs them internally in the __str__, which prints DD day(s) HH:MM:SS.ssssss (omiting days and microsecs, if not present). This does not suit everybody, at least because the word “days” is in English or when the fractional seconds are not wanted in the output.

And given the popularity of the SO question “Format timedelta to string” (link) `, there is demand for it.

2 Likes
5

Do you think this would require a PEP if I want to get the ball rolling on this, or would a GitHub issue suffice?

6

Agreed. There does need to be a way to access broken down values using a new method, if the attributes get deprecated.

3 Likes
7

I use .days a fairly regularly for things like if delta.days >= 90 checks. I’d be sorry to see it go [1].

  1. even knowing I can do my own .total_seconds() // (60 * 60 * 24) arithmetic ↩︎

2 Likes
8

You can do delta >= timedelta(days=90).

7 Likes
9

A simple issue would be enough.

2 Likes
10

Just in relation to Serhiy’s comment about it being fine to drop these, I’d like to understand better what the motivation is for keeping exposing this via a method.

Would it be sufficient to recommend that users use their own function like:

def timedelta_tuple(v):
    return v // timedelta(days=1), v // timedelta(hours=1), ...

Or is there some underlying worry about performance?

If the primary usecase is formatting, is introducing a __format__ method an option?

1 Like
11

There are issues with the tuple representation.

  • You missed weeks and milliseconds. If represent the timedelta value in units that correspond to the constructor arguments.
  • In future the precision of the timedelta objects can be improved, so we will need to add nanoseconds, so the size of the tuple will change. If your ansver to the first problem was that microseconds include milliseconds, then what about nanoseconds?
  • The order of components does not match the order of the constructor arguments.
2 Likes
12

Do we really need a separate member for microseconds? Why can’t they just be part of the seconds, a float?

2 Likes
13

Indeed.

You need these values to convert timedeltas to other objects or to rebuild values having e.g. the values rounded to the next second, minute or hour.

I’d suggest to simply return the internally stored values as a tuple: (days, seconds, microseconds). microseconds could be made a float to enable increasing the resolution to nanoseconds at some point.

14

Timedalta computations of all kinds are implemented in the datetime module. My tuple proposal was written focusing on the use-case of exporting values so they can be easily converted to other formats, including human readable messages. In this area the timedelta class does not excel.

That’s why I did not pay attention to constructor arguments, their order and that’s also the reason I omitted weeks. Some prefer 90 days, some 13 weeks, some 3 months (approx.). It’s up to them how they format it.

Of course if there is a room for improvement, let’s do it in a better way. I’ve shown that: (1) the __str__() itself needs these values. (2) A large crowd of SO users was looking for them too.

15

This is not directly related, but comparison and arithmetic operations need to represent a timedelta as a single integer – total microseconds currently. Only formatting needs representing via other units. So we could change the internal representation of timedelta objects.

17

Since it’s not clear how to play all this, I think the change will need a PEP.

3 Likes
18

Or perhaps just (days, seconds), with days being an integer and seconds a float. This is how stored time delta values in mxDateTime and it has proven to be sufficient.

1 Like
19

I feel that documented attributes of such a widely used class should have a deprecation period longer than 5 years.

7 Likes
20

I believe the idea is to still match Anton’s original proposed deprecation period of 10 years

5 years with the deprecated decorator but no runtime warning, then another 5 years with the actual DeprecationWarning at runtime

2 Likes
21

I would point out that the .days value is unbounded and thus doesn’t have the same footguns as the other attributes. I would argue this property should be kept as-is, even as the other properties are (appropriately) deprecated.