# [Datetime-SIG] Calendar vs timespan calculations...

Tim Peters tim.peters at gmail.com
Sat Aug 1 07:16:14 CEST 2015

```[Tim]
>> Speaking of which, the current tzinfo API has no way to ask "is this
>> an ambiguous time?"

[Alexander Belopolsky]
> I was hoping that we would agree on the name of the flag before
> someone asks this question. :-)

You doubtless noted that I called it "first" near the end of my
message without putting up any stink at all ;-)

> With my proposal, a naive datetime t is ambiguous in timezone tz if
>
> tz.utcoffset(t) < tz.utcoffset(t.replace(first=False))
>
> or "is this an invalid (missing) time?"

Unless I'm missing your intent entirely, that's a fine illustration of
my "The logic is bound to be annoying enough that we'd want to
concentrate it in tzstrict".  The problem I see is that the expression
you gave can never be true.  The math is indeed trivial, but a key
part works "the opposite" of how even people who've thought a lot

Two cases:

1. t.first is False.  Then the expression obviously returns false (the
LHS and RHS are applied to two datetimes all of whose components -
including .first - are the same, so both utcoffset()s return the same
value, and "<" is false because they're equal).  But if t.first
(False) is telling the truth, t _is_ the later of two ambiguous times.
So we wanted an expression that returned true in that subcase.  The
result is correct only when t.first being False is lying (i.e., when t
is not the later of two ambiguous times, but t.first is False despite
that).

2. t.first is True.

2a.  And t is not an ambiguous time.  Then I expect the two
utcoffset()s return the same value, and the expression correctly
returns False

2b. And t is an ambiguous time.  Then t is the earlier of the two
times (that's what t.first is True means in this case) , and the
constructed datetime is the later.  Obviously the earlier time should
compare less than the later time, but that's not what's being
compared.  The offsets _from_ UTC are being compared, and it's the
earlier time that has the _greater_ offset (that's the part 90% of
people "instinctively" get backwards).  So again the expression
returns False incorrectly (although would be correct in this case if
">" were used instead - but then 90% of people would instinctively
think the logic is backwards).

So in all cases the expression computes False - unless I'm missing
your intent entirely (in which case I trust you won't be shy about
enlightening me :-) ).

Why do people get this backwards?  I've pondered that off & on for a
long time.  I think it goes like this:  at a given UTC time u, then,
say, u+1 is obviously an earlier time than u+2.  So the greater the
offset the later the time.  That's intuitively obvious.  What it
wholly misses is that it's got nothing to do with what we're _trying_

We're trying to ask about how times act on a non-UTC clock.  In the
bogus reasoning, u+1 and u+2 look an hour apart on the UTC clock, so
are irrelevant to the real question.  When looking at a non-UTC clock,
the offsets have to be _subtracted_ from that clock's idea of time to
determine corresponding UTC time, and it's the negation that reverses
the sense of the comparison needed.  For an ambiguous local time T:

offset1 < offset2   # if and only if (negate, which also reverses
the direction of comparison)
- offset1 > - offset2  # if and only if (add T to both sides)
T - offset1 > T - offset2  # if and only if (and now we have the
UTC equivalents)
UTCtime1 > UTCtime2

So we can't expect most people to get this right.

Wouldn't this work?  t is ambiguous if and only if

tz.utcoffset(t) != tz.utcoffset(t.replace(first=not t.first))

That is, t is ambiguous iff the value of t.first makes a difference to
the offset.  I expect people _could_ get that right most of the time,
but may have trouble remembering "the trick".  But nobody could screw
up what, say, a new tz.is_ambiguous(t) means.

> I was hoping to sneak in a rule that for an invalid time t
>
> tz.utcoffset(t) > tz.utcoffset(t.replace(first=False))

I don't want to try to figure out what that _really_ does, although as
noted at the end of case 2b above that expression returns True when
t.first is True and t is in fact the earlier of two ambiguous times.

Because local "missing times" have no spelling in UTC, I doubt there's
any way for simple .utcoffset() expressions to detect one reliably.
IIRC, the Python docs say nothing whatsoever about how missing times
are, or "should be", handled in conversion.

But if the tzinfo class has any intelligence about the rules it's
implementing, it should be easy for a new tz.is_missing_time(t) method
to apply that intelligence.

Or, say, just a single new tz.classify(t) method returning, say, an
or'ing of flags from these two sets:

# set 1 - exactly one will be in the result
TZ_HAPPY_TIME = 1
TZ_MISSING_TIME = 2
TZ_AMBIGUOUS_TIME = 4

# set 2 -  at most one will be in the result, and none with TZ_HAPPY_TIME
TZ_DUE_TO_DST_TRANSITION = 64
TZ_DUE_TO_BASE_OFFSET_TRANSITION = 128

> (I really don't want  tz.utcoffset(t) to ever raise an exception)

Me neither.

> and of course, for most of the times
>
> tz.utcoffset(t) == tz.utcoffset(t.replace(first=False))

Agreement at last ;-)  Although I'd spell it

tz.utcoffset(t) == tz.utcoffset(t.replace(first=not t.first)

as a pretty direct translation of "the value of t.first makes no difference".

>> The most important new question callers will want to resolve  is "what should
>> `first` (aka is_dst) be now?".

> I want most callers

Gloss:  by "callers" I mean not just Python users, but also people
_implementing_ the new stuff.  Perhaps you do too.

> to be able to get away with not knowing that
> `first` exists and consistently get the earlier time from an ambiguous
> input and some "nearby" time from an invalid input.

In the case of a missing time, it's reasonable to guess they
definitely intended a time later than the closest preceding (on the
local clock) valid time.  It's also reasonable to guess they
definitely intended a time earlier than the closest succeeding (on the
local clock) valid time.  Happily, there is no possible local time
satisfying both ;-)  But there's no sensible way to compute either
without knowing "the rules" (did DST cause us to miss an hour?  an
hour and 30 minutes?  just 15 minutes?  did a politician decree we
lost 2 hours?  in any case, how long ago did time _start_ to go
missing?  and when will it stop going missing?).  Seems again a case
that requires some intelligence _in_ the tzstrict class, not heroic
efforts by callers restricted to utcoffset() alone.

> A careful application will have to call tz.utcoffset() with both values of the
> flag and either warn about the default choice or ask the user for an

As above, how can one programatically pick a valid default when faced
with a missing time?  The zoneinfo-like databases express this stuff
by giving parameters for a specific algorithm.  One relatively simple
rule can cover a vast span of time.  "It's easy" for code that _knows_
that stuff about the timezone.  If all the programmer can know is
.utcoffset() results at specific instants of time, I expect the best
they can do is loop, incrementing (or decrementing) by a naive minute
at a time (Python restricts UTC offsets to multiples of a minute),
until they find a roundtrip fixed point (i.e., the nearest local time
that "gets itself back" when converted to UTC and back again).

Isaac earlier sketched a mathematical framework for a different
approach to computing UTC offsets, which explicitly materialized that
it's a function made up of a sequence of continuous monotonically
increasing functions ("jumps in time" are discontinuities in the
range, and that's what separates one function from the next).  The
start and end of each function's domain is explicit, and so then also
are the start and end of each function's image.  This makes pretty
much all conceivable elementary questions solvable by, at worst, forms
of binary search.(e.g.,"is this a missing time", "if so, what's the
next closest valid time (in either direction)", "how long until the
next transition of any kind?", "how many transitions of any kind
occurred in the past 1000 years?" ...).

But it's far more general than needed for any real-world time zone -
and there's no code for that either ;-)
```