bpo-36138: Improve docs about converting datetime.timedelta to scalars.

[0xYasser]

https://bugs.python.org/issue36138

[scotchka]

Perhaps add a note of caution about rounding errors, and that to get the highest precision, directly calculate the total microseconds as integers?

[ncoghlan]

@scotchka There's an existing paragraph about the precision loss arising from the conversion to floating point in the total_seconds() documentation, so is your comment relating to the table entry?

In both cases, pointing to divmod as a way to avoid the precision loss would make sense.

[scotchka]

@ncoghlan The doc currently says "Note that for very large time intervals (greater than 270 years on most platforms) this method will lose microsecond accuracy."

But in general, one can also get tripped up with a small interval, for a slightly different problem:

int(timedelta(0, 1, 1).total_seconds() * 1_000_000)  # convert to total microseconds
>>> 1000000

I'm no expert on computer arithmetic, but divmod does seem to avoid such issues. (To be honest, I'd probably carry out the integer multiplication and summation of the components the "long" way, just so I don't have to think about it 😃 )

[scotchka]

Realized and confirmed that divmod is implemented with operations on the underlying integers.

[ncoghlan]

@scotchka The precision loss in your short-interval example is coming from using a truncating conversion from float to int together with decimal-vs-binary floating point representations, not any loss of precision in the original total_seconds() conversion:

>>> from datetime import timedelta
>>> timedelta(0, 1, 1).total_seconds()
1.000001
>>> timedelta(0, 1, 1).total_seconds() * 1e6
1000000.9999999999
>>> int(timedelta(0, 1, 1).total_seconds() * 1e6)
1000000
>>> round(timedelta(0, 1, 1).total_seconds() * 1e6)
1000001

Given that, I'm going to merge this as is for master and 3.7, and if we decide to add extra references to divmod, that can go in a separate PR.

[miss-islington]

Thanks @0xYasser for the PR, and @ncoghlan for merging it 🌮🎉.. I'm working now to backport this PR to: 3.7.
🐍🍒⛏🤖

[bedevere-bot]

GH-12362 is a backport of this pull request to the 3.7 branch.