Keep original input for DateDelta

[aquarhead]

Hi, we are currently looking into adopting this library in our Python backend to handle especially "Duration" in a sane way, however we soon discovered a rather unexpected behaviour where the DateDelta units are being converted.

After some digging we found this has been discussed in #110 however I don't agree with the points being made there. We are exposing these Durations as a core configuration to our users and it would be pretty bad UX if they input "3 weeks" and it always get converted into "21 days", and vice versa. In our use case, it's a lot better to use a specific time unit so that users can align their expectations and don't need to convert the units back and forth - if they configure the view to be weekly, it's much easier to compute "3 weeks later" instead of "21 days later" in ones head.

>>> from whenever import DateDelta
>>> DateDelta(months=36).format_common_iso()
'P3Y'
>>> DateDelta(weeks=3).format_common_iso()
'P21D'

And for reference this doesn't happen in jiff (where I was pointed to whenever for Python integration)

$ biff span iso8601 2y36months3w60d
P2Y36M3W60D

I was also wondering if the ISO8601 standard has anything to say on this matter, but couldn't find any reference, would be great to know if there is a standard on this.

I would like to open a discussion before maybe working on a PR, since I really only care about the immediate save then display case (i.e. parse+format returns the same data) I'm thinking one way to do it is to only keep track of "original years" and "original weeks" input, use them if nothing changed but ditch them as soon as any calculation is performed (when adding/subtracting, convert to months+days first).

[ariebovenberg]

Hi @aquarhead thanks for posting the issue and taking the time to read up and make your case. The delta API is still somewhat in flux (#108), some I am open to changing it.

The frustrating thing about the delta API is that there are a lot of wishes that contradict each other (e.g. “fewer classes” and “type safety”). The question of normalization is similar.

On the one hand, I completely understand there’s a case for keeping the “unnormalized” input (“3 weeks”). The drawback is that equality becomes surprisingly unintuitive (e.g. DateDelta(weeks=1) != DateDelta(days=7)). Compounding this is that Python doesn’t allow you to “opt out” of the equality operator as Rust does. For calendar units though (i.e. DateDelta), I can see how the advantages of “unnormalized” input outweigh the downsides, because you probably won’t be doing much arithmetic anyway. However, for exact time units (TimeDelta with hours, minutes, etc.) the argument is exactly the opposite: arithmetic is common, and few users (in my experience) would care to distinguish “60 minutes” from “1 hour”.

So, in theory you could have an unnormalized DateDelta and a normalized TimeDelta, then you’re stuck with DateTimeDelta. This would have to be unnormalized as well, because a “mixed” normalization would be far worse.

I suppose it all comes down to naming then. I really want to prevent people from accidentally using DateTimeDelta over TimeDelta and not realizing its semantics are way different (see also BurntSushi/jiff#32). Ideally, the name could reflect how the duration units are represented individually.

Some names I’ve come up with (some more realistic than others):

• Span, Duration, Period. These are in use by other libraries, but I feel they don’t emphasize enough the footguns of the concept.
• HumanDelta, VerbatimDelta, DeltaExpression, ExplicitDelta, LiteralDelta, UnnormalizedDelta. Emphasizes how it expresses a duration “literally” as humans do.
• DeltaCounter, ComposedDelta, DeltaParts, DeltaItems, ItemizedDelta, MixedDelta, DeltaBag, DeltaFields expresses how it’s just a “bag” of duration units
• IsoDelta expresses how it mirrors ISO8601 durations, a major use case. Downside is that these delta’s aren’t always used in ISO formatting contexts.

---

Another question I’m interested in whether a “calendar unit only” (DateDelta) type is worth it. Mostly libraries don’t have it, although java.time does, and NodaTime may be considering it (nodatime/nodatime#1435). Do you have any thoughts on this?

[aquarhead]

Thanks for the thoughtful reply! I will take a look at the various links you posted later, just some quick thoughts:

Another question I’m interested in whether a “calendar unit only” (DateDelta) type is worth it.

Can't answer in general, but for our case having it is absolutely wonderful, the majority of our system focus on high level supply chain management, and we definitely don't want to go below "day", so it's really nice to have a dedicated type to express just what we support.

Just from my perspective, the current split makes sense and since I enjoy Rust a lot I really appreciate the "type safety" (as much as you can get in Python) and misuse prevention.

I also think "Delta" is a pretty good name (compared to "Span") and it naturally suggests usage in calculation, I'm not sure how much it would be used for equality check 🤔 - and on that matter I feel like it makes sense to 'normalize' first and compare, if one wants the "3 weeks" != "21 days" behaviour they could for example compare the ISO format, or have a 'iso_eq' method, Python feels very lacking in this regard indeed.

Of course all these is just one user's perspective, so I understand you have to consider other factors. Just want to say I really appreciate your work and sharing your thoughts 🙏

[ariebovenberg]

One interesting idea: if delta's would be implemented "sparsely" (i.e. similar to collections.Counter or defaultdict(int)), it could mesh nicely with #108:

(Using the placeholder name “verbatim” for now)

# subtracting two dates requires explicit units
>>> delta = d1.diff(d2, units=("years", "months")) 
VerbatimDateDelta("P3y8m")

# you can easily translate these values into more usable formats:
>>> delta.tuple()  # possible because years and months are the only attributes set
(3, 8)
>>> delta.dict()
{"years": 3, "months": 8}
>>> delta.format_iso()
"P3Y8M"