use of 'float' type seems unwise

[bxparks]

I'm probably going to ruffle some feathers, but I have to write this up for the record.

When creating #295, I noticed that a number of methods returned a float, which was surprising to me. I expected these to return an int:

• TimeDelta.in_seconds() -> float
• TimeDelta.in_milliseconds() -> float
• TimeDelta.in_microseconds() -> float

Now I am noticing a more pervasive use of the float type in the parameters for other things, for example,

• Install.add(...), subtract(...)
• TimeDelta(...) constructor

I feel that the use of float is a foot-gun that should not exist in a date-time library.

1)) I think the vast majority of programmers do not understand floating point numbers and operations. How many Python people would be surprised that 0.1 + 0.2 == 0.3 returns False? Too many.

2)) So they learn something about floating point rounding errors in a base-2 system. Do they know the difference between 32-bit floating versus 64-bit floating in the IEEE-754 specification? (My thesis involved 6 years of numerical simulations, and even I don't have a good understanding of IEEE-754). Or the number of bits in the mantissa, and how that translates to decimal precision? This is even before we go into +0.0 being different from -0.0, and +Inf versus -Inf, and of course the NaN that will eventually bite them in the ass? We haven't even covered subnormal numbers.

3)) After learning all that, most people will still make the mistake of using equality to compare floating point numbers, i.e. if x == y. That is almost always a mistake, but not always a mistake unfortunately.

My preference is that the float type should not be used in a date-time library. It will bite people with hard to debug bugs.

Among the major date-time libraries that I have some familiarity with, I can't recall seeing a float type used: Noda Time, java.time, libc, go.time, C++ std::chrono. The exception is the Python datetime library, which of course has design defects that whenever is trying to fix. I think one of the things that should not carry over is the use of a float type.

The removal of the float type means that all of the round() functions can be removed. I think that's a good thing. Less code to maintain and document.

If someone wanted to get a float from an Instant, my preference is that that they call Instant.nanoseconds() then divide by 1e9. This way, the user is explicitly invoking a float type, and they are consciously opting into all the problems associated with a float type.

[ariebovenberg]

Thanks for writing this up — I agree with much of your reasoning here. You’re absolutely right that most developers don’t fully understand the footguns of floating-point numbers, and that other ecosystems (like Java, Go, or C++) tend to be much stricter about avoiding float in date/time APIs.

To clarify: whenever does not use floats internally. All internal calculations are done in integer seconds/nanoseconds. The use of float only appears at the boundaries, because in Python, this is unfortunately what almost everyone expects (and uses) for fractional numbers.

This is very much a “practicality beats purity” situation. If Python had a more widespread numeric type for representing fractional values precisely, I’d use it. But in practice, float and int are the only numerical types that see real-world use in Python. Even though Decimal would be more “correct,” it’s unfamiliar to most users and introduces friction. It also isn’t perfectly precise either (Decimal("1") / Decimal("3") illustrates that), so it doesn’t fully solve the problem.

For methods like in_seconds() or in_hours(), I think they should always exist — the question is what type they should return, and how to manage the tradeoffs. Returning an int would require each function to define its own rounding behavior, complicating both the API and the implementation. Returning a float, by contrast, delegates rounding to the caller — a cleaner separation of concerns, and more in line with user expectations.

You’re right that in principle, floats can lose precision, but in practice, it’s very hard to find real-world cases where this matters. For example:

TimeDelta(seconds=.0000018).in_hours() == 0.0000000005
TimeDelta(seconds=5).in_hours() == (5 / 3600)
TimeDelta(seconds=0.1 + 0.2) == TimeDelta(seconds=0.3)

These both work fine. You start seeing precision loss only at absurd magnitudes like:

TimeDelta(hours=24 * 365 * 9999, nanoseconds=1).in_hours()

At that point, nanosecond accuracy simply isn’t meaningful.

One important nuance: for timestamps, I completely agree that floats are a footgun. That’s why timestamp() methods return int timestamps, not float. Durations are more flexible by nature — users often want fractional hours, days, etc.

Lastly, removing float doesn’t make round() obsolete — its purpose is actually to support precise rounding without using floats. It’s there so users can explicitly control that precision without falling into float pitfalls!

I’m definitely open to revisiting this if concrete precision issues turn up in real use cases — but so far, I haven’t seen any that outweigh the simplicity and predictability of the current approach.

[bxparks]

For methods like in_seconds() or in_hours(), I think they should always exist — the question is what type they should return, and how to manage the tradeoffs. Returning an int would require each function to define its own rounding behavior, complicating both the API and the implementation. Returning a float, by contrast, delegates rounding to the caller — a cleaner separation of concerns, and more in line with user expectations.

I'm not sure that each of the in_xxx() -> float should exist. I note below that I probably would have provided a single TimeDelta.seconds_as_float() method, and let the user scale the number to their desired unit.

TimeDelta(seconds=0.1 + 0.2) == TimeDelta(seconds=0.3)

Hmm, this is unexpected to me. If 0.1 + 0.2 != 0.3, then I would have expected that their TimeDelta to obey the same equality behavior.

One important nuance: for timestamps, I completely agree that floats are a footgun. That’s why timestamp() methods return int timestamps, not float. Durations are more flexible by nature — users often want fractional hours, days, etc.

I'm not sure that I understand why float is a footgun in timestamp() but not in_seconds(). But I see your point that users may want to convert TimeDelta into imprecise time units. I would have provided just a single method, say TimeDelta.seconds_as_float(), and let the end users deal with the problems with floating point numbers. My version of your API would be:

• TimeDelta.in_seconds_as_float() -> float: nanosecond precision? No, we don't have enough bits, so maybe millisecond precision.
• TimeDelta.in_seconds() -> int
• TimeDelta.in_milliseconds() -> int
• TimeDelta.in_microseconds() -> int
• TimeDelta.in_nanoseconds() -> int

Lastly, removing float doesn’t make round() obsolete — its purpose is actually to support precise rounding without using floats. It’s there so users can explicitly control that precision without falling into float pitfalls!

I would consider rounding modes to be out-of-scope of the library. People who are using floats having already lost the internal nanosecond precision, so I'm not sure they would care much about the various rounding modes. [Edit: I meant that I don't think the users would care about the rounding modes coming out of this library. They would obviously care about rounding afterwards, for example, when displaying that information to their own end-users.]

We've talked mostly about the output type -> float. What about the input float types, like PlainDateTime.add(...), what's the semantics of the floating point parameters? Do you convert them into nanoseconds internally, for each parameter? So if the user wrote add(seconds=1.001, milliseconds=2), the result is 1s 3ms? That has too many footguns for my taste. I would make those input parameters int.

[ariebovenberg]

Good points — I can actually relate to the idea of explicitly naming the float conversions. Something like in_hours_float() or in_seconds_float() would make that intent crystal clear, and I’d be open to that pattern if we apply it consistently across all units. It also reads quite naturally in real-world use, e.g.

if delta.in_hours_float() > 1.5:
    ...

That’s a perfectly valid and common use case.

On the timestamp side: I didn’t explain the distinction well before. The reason I’m stricter there is that timestamps are primarily for interop and storage. In those contexts, precision and stability across systems matter more than human readability — which makes float uniquely unsuitable. Durations, by contrast, are often directly used for user-facing logic (“1.5 hours left”) where the convenience of fractional values outweighs the theoretical purity of using only integers.

Re: the 0.1 + 0.2 example — you can think of TimeDelta as behaving like a Decimal fixed to 9 decimal places. The equality check operates at nanosecond precision, so in practice it won’t reproduce the classic float comparison pitfalls.

On float inputs: I actually had the same hesitation initially, but in testing, I couldn’t find any concrete footguns. The internal representation always converts to integer nanoseconds immediately, and there’s no precision loss within the supported range. Even large values like TimeDelta(hours=24 * 365 * 9999, nanoseconds=1) behave predictably. Meanwhile, the convenience of add(hours=1.5) or TimeDelta(hours=1.5) is just too big to ignore — users expect that syntax to work naturally in Python.

Regarding rounding — are we perhaps talking about different things? The TimeDelta.round() method isn’t related to floating-point rounding at all. It’s for rounding durations to arbitrary increments, e.g. nearest 5 minutes, or up to whole hours (say, for billing). That’s a pretty common and useful operation, even when all calculations remain integer-based.

[bxparks]

If we added the word float to those methods, yes, that would address most of my concerns. Because the behavior of the int versions and the float versions would be explicit and obvious.

We might consider placing the float before the noun, because it sort of acts like an adjective. I think the following reads slightly better in English:

• TimeDelta.in_float_seconds()
• TimeDelta.in_float_minutes()
• TimeDelta.in_float_hours()

On the timestamp side: I didn’t explain the distinction well before. The reason I’m stricter there is that timestamps are primarily for interop and storage. In those contexts, precision and stability across systems matter more than human readability — which makes float uniquely unsuitable. Durations, by contrast, are often directly used for user-facing logic (“1.5 hours left”) where the convenience of fractional values outweighs the theoretical purity of using only integers.

Ok, that makes sense, the difference is the common usage of timestamp() versus a TimeDelta. I agree with you that people would want to convert TimeDelta into imprecise float units.

On float inputs: I actually had the same hesitation initially, but in testing, I couldn’t find any concrete footguns. The internal representation always converts to integer nanoseconds immediately, and there’s no precision loss within the supported range. Even large values like TimeDelta(hours=24 * 365 * 9999, nanoseconds=1) behave predictably. Meanwhile, the convenience of add(hours=1.5) or TimeDelta(hours=1.5) is just too big to ignore — users expect that syntax to work naturally in Python.

The scenario that concerns me is this. Programmer 1 writes something like the following:

delta1 = ...
delta2 = ...
delta3 = ...

if (TimeDelta(seconds=delta1+delta2) == TimeDelta(seconds=delta3)):
    # do something

Then Programmer 2 comes along, refactors the code, and sees all that inefficient clutter and overhead of extra object constructions, and simplifies this down to:

delta1 = ...
delta2 = ...
delta3 = ...

if (delta1 + delta2 == delta3):
   # do something

This new code will work like the previous code, almost all the time. In isolation, maybe the code reviewer would catch this. But if this change was part of a much larger pull request, it could easily be missed. Because catching this bug requires the code reviewer to know a number of things which may not be obvious:

• that delta1, delta2, and delta3 are float types
• that TimeDelta converts everything to nanosecond precision
• that its __eq__ does not follow the same behavior as floats, and
• that the equality operator == on a float has a bunch of foot-guns, that it could fail, but only for certain values of the float

This bug might be found quickly with sufficient unit tests. But even it was caught in unit testing, it mgith take the developer many hours or days to figure out why it's failing. In the worst case, the code would pass all the unit tests, because the tests were done using integers. And this gets pushed out to production, and the application fails, randomly, because only certain values of float would trigger it.

I don't think the risk is worth it.

[Edit: On the other hand, if TimeDelta has functions that return a float type, the users may expect that they can put the results back into a TimeDelta object. I might end up agreeing with you on this eventually.]

Regarding rounding — are we perhaps talking about different things? The TimeDelta.round() method isn’t related to floating-point rounding at all. It’s for rounding durations to arbitrary increments, e.g. nearest 5 minutes, or up to whole hours (say, for billing).

You are right! I misunderstood the behavior of round(). I was probably traumatized by seeing the float type, and I automatically assumed that round() was related to that. I withdraw my concerns about round()... except that the various modes don't seem to be documented. At least I couldn't find them.