Closed bxparks closed 3 months ago
Interesting.
For detecting ambiguity, there already is a disambiguated()
method that checks if a time can be considered ambiguous. In 0.4 it will be renamed to is_ambiguous()
Regarding exposing the fold
value: in the current version, ZonedDateTime
does expose a fold
attribute, it just is mistakenly undocumented. However, I will be removing it in version 0.4 because no other language I know of stores the disambiguation: the standard seems to be storing the offset instead.
As an alternative, perhaps something like disambiguation()
can be added later, which returns an enum like NOT_AMBIGUOUS | EARLIER | LATER
or something...
also: I also wish that ZoneInfo
objects themselves had methods like is_ambiguous
...
is_ambiguous()
is now part of ZonedDateTime as of 0.4. The
foldattribute is considered an implementation detail and can be retrieved from the underlying datetime with
dt.py_datetime().fold`
As far as I can tell,
ZonedDateTime
, which inherits fromDateTimeAwareDateTime
time, does not expose the underlyingfold
value: https://whenever.readthedocs.io/en/latest/api.html#whenever.ZonedDateTime https://whenever.readthedocs.io/en/latest/api.html#whenever.AwareDateTimeIt may not be obvious that the
fold
parameter described by PEP 495 is both an input parameter and an output parameter. The outputfold
parameter is what allowsdatetime.datetime
to support round trip conversions without loss of information. In other words,epoch_seconds
can be converted intodatetime.datetime
, which can then be converted back toepoch_seconds
, and the 2epoch_seconds
will be identical, even during an overlap (when, for example, northern hemisphere countries "fall back" in the fall).But more practically, the
fold
parameter of adatetime.datetime
object is useful to a client app, because it allows the app to know if a specificepoch_second
was converted to adatetime
which could be interpreted by humans as ambiguous. Access to thefold
parameter is required if the application wants to warn the user of an ambiguous time, something like: "The meeting time is 01:30 on Nov 3, 2024 (Warning: this is the first occurrence of 01:30, not the second occurrence.)"Currently,
ZonedDateTime
is a thin wrapper arounddatetime.datetime
. But it does not expose thefold
parameter to the calling client. I think it should, but in a way that is more friendly thanfold
. As I was writing this ticket, it occurred to me that there is a complication: the underlyingdatetime.datetime
class, which is used byZonedDateTime
, does not actually contain enough information to solve this problem properly. We actually needZonedDateTime
to expose two bits of information:1)
is_ambiguous: bool
: Whether or not theepoch_seconds
mapped to aZonedDateTime
that can be ambiguous, i.e. a "duplicate" or an "overlap". Alternative names for this property may beis_overlap
oris_duplicate
. 2)fold: int
: 0 if theZonedDateTime
corresponds to the first instance, and 1 if theZonedDateTime
corresponds to the second.The
is_ambiguous
parameter can be calculated by brute force withinZonedDateTime
. But it would be more efficient to delegate that calculation to aTimeZone
class (which does not currently exist inwhenever
, but I described its contours in #60), so that we get efficient access to the metadata information about the given timezone.Anyway, I don't know how you want to prioritize this issue. I figure that if you are going make a clean break from
datetime
, and solve a bunch of problems, you might as well fix this one too. :-)