Feedback on whenever v0.9.2

[bxparks]

Hello Arie,

I finally had some time to validate and use the whenever library. I downloaded 0.9.2 from PyPI. (BTW, your GitHub Releases page has the "latest" pinned to 0.9.1). I have some bug reports and comments, and I thought I should send them to you before whenever is bumped to v1.0.

I divide my feedback into 5 sections:

• Kudos
• Bug: Incorrect DST Transitions and UTC Offsets
• Missing or Desired Features
• Surprising or Confusing
• Documentation Fixes

Kudos

• The separation of datetime into ZonedDateTime and Instant is wonderful. Makes the calling code easier to understand and maintain.
• Changing LocalDateTime to PlainDateTime. I supported this last year, and I support it now.
• Your https://whenever.readthedocs.io/en/latest/index.html documentation is very well done.
• Fast. The TZDB resolution Rust library seems fast.

Bug: Incorrect DST Transitions and UTC Offsets

This is the most serious. I will file a separate Issue after I finish writing this. (Done: #296)

As I understand, you have delegated the TZDB processing to a Rust library. It appears that the Rust library calculates the wrong DST transitions and UTC offsets for a large number zones in the TZDB database, for their earliest years (say < 1960 or so). Since the early DST transitions are incorrect, this produces incorrect UTC offsets from the year 0001 to about 1950 (depending on the zone). The problem affects 286 zones out of 340 zones in TZDB 2025b.

Missing or Desired Features

I ported a bunch of scripts and code to whenever, and I noticed several missing features. It would be great to have these.

DST Offset From ZonedDateTime

Given a ZonedDateTime, I want to obtain the current DST offset. This allows the calling code to determine if the user in a particular timezone is observing DST time or STD time. The client code can then prompt the user, "You are observing DST time. Did you mean XXX instead?"

Abbreviation From ZonedDateTime

The TZDB defines an abbreviation for every timezone at every moment. For example, "PST" for Pacific Standard Time, or "CET" for Central European Time. As far as I can tell, ZonedDateTime does not expose this information. I would like a ZonedDateTime.abbrev property.

Yes, abbreviations are not unique, and shouldn't be used in situations where accuracy is required. But for everyday use by normal people, living in a fixed or limited number of timezones (e.g. USA or Canada), displaying the time using the abbreviation is useful and more familiar than ISO 8601 or RFC 3339 format.

IsGap or IsOverlap from PlainDateTime

Given a PlainDateTime and a tz, I want to know whether the user-provided plainDateTime is in a gap or an overlap. I don't see way to do that in the current API.

The ZonedDateTime.is_ambiguous() does not do what I want. Because ZonedDateTime automatically disambiguates the invalid plainDateTime before returning the fully constructed object. Calling is_ambiguous() always returns False for a gap.

I think what I need is PlainDateTime.disambiguation(tz: str), which returns an enum or an int corresponding to Unique, Gap, or Overlap. This allows me to prompt the user like this: "The date you have entered does not exist. Did you mean XXX?" Or, "The date you have entered is a duplicate. Did you mean YYY?"

You could argue that the disambiguation() function does not belong on PlainDateTime, because it is not supposed to know about timezones. You would be right. It really belong in a TimeZone object, like TimeZone.disambiguate(pdt: PlainDateTime) -> int.

Unfortunately, the whenever library does not expose a TimeZone object. I may have mentioned last year that exposing a TimeZone object has a lot of advantages. It allows methods like disambiguate(PlainDateTime) -> int, and things like TimeZone.transitions(start_year: int, until_year: int) -> List[PlainDateTime] which returns the list of all transitions from start to until year. But it does make the API slightly more complex.

Version Numbers

For validation and testing, it's useful to know the version numbers of the TZDB database (e.g. "2025b") and the version number of the whenever library ("0.9.2"). I don't see a way to get this information.

Surprising or Confusing

I understand that most of the following is probably bikeshedding. You have probably thought through the pros and cons of various options. But I want to give my feedback on my first impressions of the whenever API, as I migrated some code over.

TimeDelta.in_seconds() Returns a Float?

I wanted to know the ZonedDateTime.offset in seconds, so I called ZonedDateTime.offset.in_seconds(), but that returns a float? Totally unexpected. Am I supposed to cast it to an int? My expectation was that in_seconds() returns an int, in_milliseconds returns an int, and in_microseconds() returns an int. [Edit: I expand on this point in #298]

TimeDelta.round(mode=) Cannot Truncate

The TimeDelta.round() takes an optional mode parameter, which is half_even by default. Maybe I missed it, but I cannot find the explanation of any of the rounding modes: 'ceil', 'floor', 'half_ceil', 'half_floor', 'half_even'. I don't know what 'half_ceil', 'half_floor, or 'half_even means.

My expectation was that round() truncates by default, because I expected that to be the most common operation. I think that means that mode must be set to... nope... I don't see a truncate option, since 'floor' does not mean 'truncate' for negative numbers. So am I supposed to cast to int() to truncate?

Why Does PlainDateTime.add() Requires ignore_dst=True ?

Why does adding and subtracting a PlainDateTime require ignore_dst=True? In my mind, a PlainDateTime does not know about DST, by definition. It represents an abstract Gregorian calendar object, without knowledge of timezones or DST. I should be able to add and subtract arbitrary hours, minutes, seconds, without limitations.

Instant.timestamp()

You are probably following the standard datetime library conventions, but I wish this was named Instant.unixseconds() for better self-documentation. I work with different datetime libraries, SQL databases, and other applications using the term "timestamp". Half the time, I don't remember what "timestamp" means in a particular context, so I have to look it up. Is it an int, a string, an object, or something else?

There is no such ambiguity with Instant.unixseconds(). I recommend unixseconds() instead of epochseconds(), because the Epoch may not be Unix Epoch, it could be something else. So unixseconds() also makes that clear.

to_tz()

A small nit: I think all other methods named to_XXX() converts the current object to the object named XXX. Except to_tz(). I don't know, maybe something else would be better? Examples:

• convert_to_tz(), or
• convert_tz(), or
• for_tz()

But I can probably get used to to_tz() eventually.

assume_YYY()

I can't quite understand why some methods are named to_XXX() and some are named assume_YYY(). I know there's an explanation in the docs somewhere (I can't find it now), but I did not understand it when I read it.

Documentation Fixes

LocalDT -> PlainDT

There is at least one place where LocalDT is used. After the rename to PlainDateTime, I think you mean PlainDT.

_LocalTime, _LocalDate

Maybe these should be renamed _PlainTime and _PlainDate? They are internal, so I guess it doesn't matter..

round(mode) Not Documented

The mode parameter of round() is not documented, as far as I can tell.

_BasicConversions.from_py_datetime()

There is a Note that says:

"The datetime is checked for validity, raising similar exceptions to the constructor. ValueError is raised if the datetime doesn’t have the correct tzinfo matching the class. For example, ZonedDateTime requires a ZoneInfo tzinfo."

It took me several attempts to understand this. I think you mean the following:

"The datetime is checked for validity, raising similar exceptions to the constructor. ValueError is raised if the datetime doesn’t have the correct tzinfo matching the class. For example, ZonedDateTime requires that the datetime has a ZoneInfo tzinfo."

[ariebovenberg]

Thanks for the in-depth feedback, I'll be going over it in depth soon.

About the bug: I have an idea what could be causing this, as I've fixed a similar bug in the upper bound before. An oversight of mine to not consider the lower bound may be affected by the same issue. Fortunately, it only affects dates in the far past--but of course still a serious thing to fix ASAP

[ariebovenberg]

The Bug should now be fixed, let me know if I missed something

Missing features

• Agree on DST offset and abbrev. They're in the data but I haven't gotten around to exposing them in the API yet

• "is gap/fold" I'm open to adding this, but I need to give this some thought. Note you can currently use:

  dt:  PlainDateTime = ...
  try:
      dt.assume_tz(my_tz, disambiguate="raise")
  except SkippedTime:
      print("time is in a gap")
  except RepeatedTime:
      print("time is in a fold")

  although it isn't very ergonomic 😉

• Getting the version of whenever is easy: import whenever; print(whenever.__version__)

• Getting the version of the TZDB is a bit trickier. This because both the filesystem and the tzdata package may be a source. tzdata also has a __version__, and on my machine the zoneinfo directory appears to have a +VERSION file, but I'm unsure if this is a standard that can be relied upon.

I'll get to "surprising" and "docs fixes" later.

[BurntSushi]

RE version: yeah my /usr/share/zoneinfo directory (on Archlinux) has no +VERSION. The version can be found in tzdata.zi, but that's not guaranteed to be there either. When I looked into this, I could surmise no standard way to get the version of tzdb.