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.