[Python-Dev] datetime.timedelta total_microseconds

[Chris Barker]

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 /
datetime.timedelta(days=7)

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()
method:

a_time_in_arbitrary_units.to('second')

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
early.

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
usable.

-CHB

-- 

Christopher Barker, Ph.D.
Oceanographer

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>