Improve .__repr__ implementation for datetime.timedelta

[musically-ut]

BPO	30302
Nosy	@tim-one, @abalkin, @vstinner, @bitdancer, @berkerpeksag, @vadmium, @serhiy-storchaka, @musically-ut
PRs	bpo-30302 Make timedelta.__repr__ more informative. #1493 bpo-30302: Update WhatsNew and documentation. #2929 Merge pull request #1 from python/master #2943 bpo-31545 Update documentation containing timedeltas repr. #3687

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2017-10-27.11:28:20.761>
created_at = <Date 2017-05-07.19:57:26.207>
labels = ['3.7', 'type-feature', 'library']
title = 'Improve .__repr__ implementation for datetime.timedelta'
updated_at = <Date 2017-10-27.11:28:20.759>
user = 'https://github.com/musically-ut'

bugs.python.org fields:

activity = <Date 2017-10-27.11:28:20.759>
actor = 'berker.peksag'
assignee = 'none'
closed = True
closed_date = <Date 2017-10-27.11:28:20.761>
closer = 'berker.peksag'
components = ['Library (Lib)']
creation = <Date 2017-05-07.19:57:26.207>
creator = 'musically_ut'
dependencies = []
files = []
hgrepos = []
issue_num = 30302
keywords = ['patch']
message_count = 35.0
messages = ['293212', '293213', '293215', '293216', '293219', '294062', '294106', '297029', '297048', '297049', '297050', '297269', '297293', '297424', '297429', '297438', '297440', '297441', '297444', '297447', '297457', '297471', '297521', '297531', '297560', '297561', '297570', '297865', '299148', '299149', '299152', '299381', '299384', '305111', '305113']
nosy_count = 8.0
nosy_names = ['tim.peters', 'belopolsky', 'vstinner', 'r.david.murray', 'berker.peksag', 'martin.panter', 'serhiy.storchaka', 'musically_ut']
pr_nums = ['1493', '2929', '2943', '3687']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue30302'
versions = ['Python 3.7']

[musically-ut]

Currently, the default implementation of datetime.datetime.__repr__ (the default output string produced at the console/IPython) gives a rather cryptic output:

from datetime import datetime as D
D.fromtimestamp(1390953543.1) - D.fromtimestamp(1121871596)
# datetime.timedelta(3114, 28747, 100000)

For the uninitiated, it is not obvious that the numeric values here are days, seconds and microsecond respectively.

Would there be any pushback against changing this to:

# datetime.timedelta(days=3114, seconds=28747, microseconds=100000)

?

[serhiy-storchaka]

The drawback is that this change increases the length of the repr. If you output few values in a row (for example output the repr of a list of timedeltas), this makes the output less readable.

Users of datetime.timedelta know what arguments mean. If they don't know they always can look in the documentation or builtin help.

datetime.datetime has more arguments, and its repr doesn't use keywords.

[musically-ut]

The drawback is that this change increases the length of the repr.

I would argue that it is a reasonable trade-off given the increase in ease of understanding.

I know that this is a weak argument, but, keywords are not without precedent. Consider the comically more verbose example:

import time
time.gmtime(1121871596)
# time.struct_time(tm_year=2005, tm_mon=7, tm_mday=20, tm_hour=14, tm_min=59, tm_sec=56, tm_wday=2, tm_yday=201, tm_isdst=0)

datetime.datetime has more arguments, and its repr doesn't use keywords.

I think that guessing the meaning of values is much harder when it comes to timedelta.

Users of datetime.timedelta know what arguments mean. If they don't know they always can look in the documentation or builtin help.

I created the issue after ... a friend ... spent an embarrassing amount of time debugging because he thought that the third argument represented milliseconds and not microseconds. <_<

I could, of course, tell him:

In the face of ambiguity, resist the temptation to guess.

But he could retort:

Explicit is better than implicit.

and

Readability counts.

I think he has a point.

[vadmium]

This was discussed fairly recently: <https://marc.info/?i=CAPTjJmrBxpvYQUYXshBC1J13M_h5or67CNBKrkySw4ef6RqDoQ@mail.gmail.com\>. There seems to be a bit of support for changing this. It is not a bug fix, so has to go into the next release, now 3.7.

I disagree that the positional timedelta parameters are well-known.

The built-in help was also discussed in that thread. I don’t think it got fixed yet, did it?

The datetime class represents absolute dates. It is nonsense to specify a date without a year. Timedelta is different, because time is measured with different units. The first parameter (days) is surprising considering most other Python APIs (sleep etc) deal with seconds.

The size of the repr could be reduced a bit by dropping the module name: datetime.timedelta vs just timedelta. Although that would be inconsistent with the other classes; I’m not sure about this.

Other improvements that I would like to see:

1. Drop leading zeros: timedelta(seconds=60) rather than timedelta(days=0, seconds=60). This would also help reduce the size.

2. Factor out the negative sign: -timedelta(seconds=60) rather than timedelta(days=-1, seconds=86340).

[musically-ut]

This was discussed fairly recently: <https://marc.info/?i=CAPTjJmrBxpvYQUYXshBC1J13M_h5or67CNBKrkySw4ef6RqDoQ@mail.gmail.com\>

That thread went deep and culminated here, as far as I can tell: https://marc.info/?l=python-dev&m=145077422417470&w=2 (I may not have explored all the branches, though.)

So there indeed seems to be general agreement about changing this. It was heartening to know that I wasn't the only one to stumble. \o/

The built-in help was also discussed in that thread. I don’t think it got fixed yet, did it?

No, the doc-string is as uninformative as then, as far as I can tell:

In [178]: datetime.timedelta?
Init signature: datetime.timedelta(self, /, *args, **kwargs)
Docstring: Difference between two datetime values.
File: ~/miniconda3/lib/python3.5/datetime.py
Type: type

I'll investigate what documentation for other functions looks like and see if I can come up with something better. The exact documentation would be best discussed over diffs on Github.

Then there is the issue of repr being explicitly documented, as you had pointed out on the Github issue. Guido thinks that any breakage is _unlikely_ but "asked around" here: https://marc.info/?l=python-dev&m=145065347022557&w=2

As far as I can tell, he didn't see an explicit response.

The size of the repr could be reduced a bit by dropping the module name: datetime.timedelta vs just timedelta. Although that would be inconsistent with the other classes; I’m not sure about this.

Personally, I don't see a big problem either way but having datetime.timedelta in the repr feels reassuring to me that I have the 'right' type instead of some other 'timedelta' from a non-stdlib module (e.g. moments or pandas).

1. Drop leading zeros: timedelta(seconds=60) rather than timedelta(days=0, seconds=60). This would also help reduce the size.

This sounds reasonable. I'll make this change and add corresponding tests.

2. Factor out the negative sign: -timedelta(seconds=60) rather than timedelta(days=-1, seconds=86340).

I'm not sure there was consensus about this; if I understand correctly, Guido thinks that it is important that the repr return what the attributes hold: https://marc.info/?l=python-dev&m=145066934224955&w=2

[vadmium]

I think the benefit of the repr being easier to understand outweighs the pain of breaking the old format. If the change is a problem, that might be mitigated by adding an entry to the “Porting to Python 3.7” documentation.

I don’t think my option of factoring the minus sign out to the front of the timedelta constructor was mentioned on Python-dev. The advantage is that it doesn’t mention problematic negative attribute values, and if you negate a timedelta, you still get the right attribute values:

>>> d
-datetime.timedelta(seconds=60)
>>> -d
datetime.timedelta(seconds=60)
>>> (-d).seconds
60

[musically-ut]

So we are okay with

datetime.timedelta(minutes=-1)
# -datetime.timedelta(seconds=60)

and

datetime.timedelta(minutes=-1).seconds
\bpo-86340

datetime.timedelta(minutes=-1).days
# -1

?

Perhaps I'm reading this incorrectly:

"If the repr() shows different numbers than the attributes things are worse than now." ~ Guido, https://marc.info/?l=python-dev&m=145066934224955&w=2

Maybe he was only talking about:

datetime.timedelta(minutes=-1)
# datetime.timedelta(minutes=-1)

but I would like a second opinion on it. :)

Also, I'll just drop the description of .repr from the .RST documentation because it is not to be relied on anyway. Any objections to that?

~
ut

[musically-ut]

I've added the following tests to remove the 0 attributes from the repr:

    self.assertEqual(repr(self.theclass(days=1, seconds=0)),
                     "%s(days=1)" % name)
    self.assertEqual(repr(self.theclass(seconds=60)),
                     "%s(seconds=60)" % name)
    self.assertEqual(repr(self.theclass()),
                     "%s(seconds=0)" % name)
    self.assertEqual(repr(self.theclass(microseconds=100)),
                     "%s(microseconds=100)" % name)
    self.assertEqual(repr(self.theclass(days=1, microseconds=100)),
                     "%s(days=1, microseconds=100)" % name)
    self.assertEqual(repr(self.theclass(seconds=1, microseconds=100)),
                     "%s(seconds=1, microseconds=100)" % name)

I am still ambivalent about factoring the minus sign outside, though.

I've also fixed a bug in test_datetime.py which prevented execution of the Python implementation in Lib/datetime.py.

TODO:

• Decide about factoring the minus sign.
• Drop description of timedelta.__repr__ from the documentation.

~
ut

[vstinner]

2. Factor out the negative sign: -timedelta(seconds=60) rather than timedelta(days=-1, seconds=86340).

Please don't do that. repr() is designed for developers, not end users. Don't make repr() implementation overcomplicated. Just dump raw data, tha's all.

If you want something more smart, use str() or even write a *new* method?

[vstinner]

What is your favorite repr() for datetime.timedelta(seconds=0)?

Since it's hard to decide which unit is the best, I suggest to not write any unit: either "datetime.timedelta(0)" or "datetime.timedelta()" is fine with me.

In fact, "datetime.timedelta(seconds=0)" is also ok, since seconds is the most common unit, no?

(Ok, to be honest, I don't really care. But I wanted to have a discussion on this issue ;-))

[musically-ut]

@Haypo: thanks for the input!

I will find datetime.timedelta() to be rather confusing because it does not explicitly tell me that the interval indeed is 0.

Between datetime.timedelta(0) and datetime.timedelta(seconds=0), I am ambivalent but I prefer the latter for consistency with the other repr.