[Python-Dev] datetime.timedelta total_microseconds

Paul Ganssle paul at ganssle.io
Wed Feb 27 10:11:54 EST 2019

On 2/26/19 7:03 PM, Chris Barker via Python-Dev wrote:
> This thread petered out, seemingly with a consensus that we should
> update the docs -- is anyone doing that?
I don't think anyone is, I've filed a BPO bug for it:

> -- I am a physical scientist, I work with unitted quantities all the
> time (both in code and in other contexts). It never dawned on me to
> use this approach to convert to seconds or milliseconds, or ...
> Granted, I still rely on python2 for a fair bit of my work, but still,
> I had to scratch my head when it was proposed on this thread.
As another data point, I also have a background in the physical
sciences, and I actually do find it quite intuitive. The first time I
saw this idiom I took it to heart immediately and only stopped using it
because many of the libraries I maintain still support Python 2.

It seemed pretty obvious that I had a `timedelta` object that represents
times, and dividing it by a base value would give me the number of times
the "unit" timedelta fits into the "value" timedelta. Seeing the code
`timedelta(days=7) / timedelta(days=1)`, I think most people could
confidently say that that should return 7, there's really no ambiguity
about it.

> -- There are a number of physical unit libraries in Python, and as far
> as I know, none of them let you do this to create a unitless value in
> a particular unit. "pint" for example:
> https://pint.readthedocs.io/en/latest/
> ...
> And you can reduce it to a dimensionless object:
> In [57]: unitless.to_reduced_units()                                 
> Out[57]: 172800.0 <Unit('dimensionless')>
I think the analogy with pint's unit-handling behavior is not completely
appropriate, because `timedelta` values are not in /specific/ units at
all, they are just in abstract duration units. It makes sense to
consider "seconds / day" as a specific dimensionless unit in the same
sense that "percent" and "ppb" make sense as specific dimensionless
units, and so that would be the natural behavior I would expect for
unit-handling code.

For timedelta, we don't have it as a value in specific units, so it's
not clear what the "ratio unit" would be. What we're looking at with
timedelta division is really more "how many <unit>s are there in this

> So no -- dividing a datetime by another datetime with the value you
> want is not intuitive: not to a physical scientist, not to a user of
> other physical quantities libraries -- is it intuitive to anyone other
> than someone that was involved in python datetime development??

Just to clarify, I am involved in Python datetime development now, but I
have only been involved in Python OSS for the last 4-5 years. I remember
finding it intuitive when I (likely working as a physicist at the time)
first saw it used.

> Discoverable:
> ==========
I agree that it is not discoverable (which is unfortunate), but you
could say the same thing of /all/ operators. There's no tab-completion
that will tell you that `3.4 / 1` is a valid operation or that (3,) +
(4,) will work, but we don't generally recommend adding methods for
those things.

I do think the discoverability is hindered by the existence of the
total_seconds method, because the fact that total_seconds exists makes
you think that it is the correct way to get the number of seconds that a
timedelta represents, and that you should be looking for other analogous
methods as the "correct" way to do this, when in fact we have a simpler,
less ambiguous (for example, it's not obvious whether the methods would
truncate or not, whereas __truediv__ and __floordiv__ gives the division
operation pretty clear semantics) and more general way to do things.

I think it's too late to /remove/ `total_seconds()`, but I don't think
we should be compounding the problem by bloating the API with a bunch of
other methods, per my earlier arguments.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20190227/df9c6872/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <http://mail.python.org/pipermail/python-dev/attachments/20190227/df9c6872/attachment.sig>

More information about the Python-Dev mailing list