Provide timezone metadata in ZonedDateTime

[bxparks]

I took a quick scan through the API doc (https://whenever.readthedocs.io/en/latest/api.html), and I noticed that the IANA TZDB timezones are always referenced symbolically, through a string (e.g. "America/Los_Angeles"). As far as I can tell, there is no explicit TimeZone class. (I assume internally, whenever is using zoneinfo or something similar.) This means that timezone metadata is not available. For example:

• tz.name() - full unique name of the IANA timezone (e.g. "America/Los_Angeles")
• tz.abbrev(timestamp) - the IANA abbreviation (e.g. "EST") at a given timestamp
• tz.stdoffset(timestamp) - the Standard UTC offset at a given timestamp
• tz.dstoffset(timestamp) - the DST offset at a given timestamp
• tz.utcoffset(timestamp) - the full UTC offset at a given timestamp (i.e. stdoffset + dstoffset)
• tz.isambiguous(timestamp) - return True if timestamp generates a ZonedDateTime whose inner DateTime representation is ambiguous
• tz.transitions(from, until) - list of DST transitions between [from, until)
• [Added] tz.version() - return the IANA TZDB version identifier (e.g. "2024a"), this is important for deterministic and reproducible integration tests

I also noticed that your AwareDateTime classes do not have methods corresponding to some of these. In other words, the following do not exist:

• ZonedDateTime.tzname()
• ZonedDateTime.tzabbrev()
• ZonedDateTime.stdoffset()
• ZonedDateTime.dstoffset()
• ZonedDateTime.utcoffset()

Admittedly, applications which need this information are rare, but they do exist. If the whenever library aims to be a general purpose replacement of the standard datetime library, then access to the TimeZone metadata may need to be added.

[ariebovenberg]

My first instinct is to agree with your points. I'm hesitant to add another class though...

Admittedly, applications which need this information are rare

There will be plenty of these type of decisions. My gut feeling is that it's best (most Pythonic, perhaps) to aim for the common use cases and leave users with complex needs to use lower-level libraries (ZoneInfo or time directly)

[ariebovenberg]

Coming back to this issue, my conclusion so far is that most metadata that can be retrieved from zoneinfo should be accessible through ZonedDateTime. At the moment, onlydst() and tzname() are available. Fine to expose these on the class. Methods like transitions(from, until) don't exist (yet). It seems sensible to submit these feature requests to cpython

[ariebovenberg]

@exoriente has expressed interest in picking up this issue.

[ariebovenberg]

Note: with the implementation of timezone logic in Rust (#202), this issue becomes a lot more involved: TZ names and DST flags would need to be added to TZif file parsing.

On the plus side, whenever's custom TZif implementation allows introduction of methods like next_transition or previous_transition which aren't available on ZoneInfo

[ofek]

I just noticed the status change. Has this been implemented?

[ariebovenberg]

@ofek @bxparks the upcoming release (0.10) adds:

• ZonedDateTime.tz_abbrev()
• ZonedDateTime.dst_offset()

See the docs here

There is now also a ZonedDateTime.format() that allows formatting with TZ abbreviation, for example.

Likely to be implemented:

• a ZonedDateTime.next_transition() method. This should be enough to get all the information on transitions.

Not (yet) implemented:

• getting the timezone DB version. This is tricky because the version isn't (always) available when using system zoneinfo files. When using tzdata from PyPI, it's a simple tzdata.__version__ lookup

[ofek]

That's awesome!

[ariebovenberg]

Pre-release 0.10.0b3 now includes next_transition()/prev_transition() on ZonedDateTime

[ariebovenberg]

Release 0.10 is now out with a lot of improvements to timezone metadata. Feel free to reopen this discussion if there are any issues.