[Python-Dev] datetime.timedelta total_microseconds

Chris Barker chris.barker at noaa.gov
Wed Feb 27 17:52:05 EST 2019

On Wed, Feb 27, 2019 at 7:15 AM Paul Ganssle <paul at ganssle.io> wrote:

> 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.
we know have two contrasting data points -- it's settled!

But I'd like to know -- I too will probably remember and use this idiom now
that I know it (if not take it to heart ...) -- but would you hvae figured
it out on your own?

>  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.
in that example absolutely -- but this is the one I'm worried about:

an_arbitrary_dateitme_returned_from_a_lib_you_didn't_write /

not so obvious.

> 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.
agreed -- but it is a use-case that is worth looking into -- folks will
either have no experience with units, or with a lib like that one (there
are more, and I think they all handle it a similar way)

And if you have a pint object representing time that you do not know the
units of, the way to get it into the units you want is to call teh to()


That is an obvious and familiar API.

> I agree that it is not discoverable (which is unfortunate), but you could
> say the same thing of *all* operators.

sure, but most operators are really widely used.

> There's no tab-completion that will tell you that `3.4 / 1` is a valid
> operation

well, THAT one had better be obvious :-)

> or that (3,) + (4,) will work, but we don't generally recommend adding
> methods for those things.

and that IS a source of confusion, but at least for the built-in types (and
ones that conform to the primary ABCs), people are going to learn it pretty

But conversion of a datetime object into particular units is a pretty
specialized operation.

Also, in most (all?) cases with builtin (and most of the standard library)
the math operators return the same type (or a conceptional same type: int /
int => float -- all numbers)

> 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,

well, yes. I for one, was very happy to have found it when I did :-) -- of
course that was py2, when it WAS the only easy way to do it.

> 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)

I don't think so, I was actually a touch surprised that:

a_timedelta / timedelta(microseconds=1)

yielded a float that may have lost precision, when the timedetla type
stores ms precision, and python ints can handle any size int.

it seems __floordiv__ does preserve precision. Which is kinda ironic --
after all, it's called "ture division" and "floor division", not "float
division" and "integer division"

My point being -- if you care about the details, you're going to have to
dig deeper no matter what method is used.

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.

I'm not a big fan of bloated APIs -- but this is not a lot of methods, with
a clear naming pattern, on an API without a huge number of methods (seven
non-dunder attributes by my count) already.

>From a practicality beats purity standpoint -- a few new methods (or a
single conversion method) is less pure and "correct", but also a lot more



Christopher Barker, Ph.D.

Emergency Response Division
NOAA/NOS/OR&R            (206) 526-6959   voice
7600 Sand Point Way NE   (206) 526-6329   fax
Seattle, WA  98115       (206) 526-6317   main reception

Chris.Barker at noaa.gov
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20190227/aa2a3b59/attachment.html>

More information about the Python-Dev mailing list