[Zope3-dev] tzinfo

[Guido van Rossum]

[Patrick]
> Wiki: http://www.zope.org/Members/fdrake/DateTimeWiki/FrontPage
> 
> The current design suggests a naive datetime class plus a subclass
> that provides a hook for others to extend the meaning of (and alter
> the calculations applied to) a naive datetime (which I will now
> simply refer to as a datetime). There seems to be something of a
> concensus that this basic approach is a good one.

(The only alternative I'm still considering is to fold the tzinfo
support into the base class -- I'll see how much extra work it is to
separate the two out and then decide.  If it turns out that datetimetz
has to override a lot of methods defined in datetime, just to add a
tz= argument, it may be more efficient to have a single base class,
and just default to tz=None i.e. naive time.  The only place where
this would add real complexity to the base class, I believe, is when
comparing and hashing datetimetz instances -- datetimetz instances
that represent the same time point in different timezones must compare
and hash equal.  We had some fairly complex code dealing with that in
the prototype before I ripped out tz support.)

> The issues that we wish to delegate to this subclass have to do with
> timezone (however that is defined) and Daylight Saving Time
> (DST). There is a fair amount of ambiguity concerning the meaning of
> these terms. Because we are delegating responsibility for resolving
> this ambiguity to a hook, I think we want to avoid implying more
> than we should with regard to this hook and the requirements we
> place on this hook.

While some people may disagree on whether Arizona and the rest of the
US mountain states are in the same timezone, I don't think anybody
will argue that calling something a "timezone issue" excludes
discussion of DST.

> For example, the hook is currently defined as a tzinfo instance. The
> name implies that the instance is for informational purposes dealing
> with timezone.

"For informational purposes" is a phrase I've seen in ISO standards
meaning stuff that's useful for the reader (like an index or an
appendix summarizing certain aspects) but which repeats stuff that's
already defined normatively elsewhere, and when the two definitions
are in conflict, the informational stuff loses to the normative stuff.

That's not what's going on here.  The tzinfo provides information
about timezone (and DST) issues that's essential for implementing
proper formatting of datetime instances representing local time in
some timezone, and for conversion between datetime instances using
different timezones.

> But one of its functions is dealing with DST, which
> some people feel is a separate concern from timezone. And a tzinfo
> subclass may do more than just supply information. So I'm wondering
> if this is the most appropriate name. Likewise, is datetimetz the
> most appropriate name?  Especially since a datetimetz with a tzinfo
> of None is the same as a datetime.

I like the names I proposed just fine and am not convinced that they
are in any way confusing or restricting.

> So, for now, I'm going to refer to datetimetz as datetimex (as in
> extended, not the watch manufacturer) and tzinfo as dtx (as in
> datetime extension).  Not that these are good names, simply that
> they are sufficiently ambiguous.
> 
> Then we get to the names of the hook methods, which datetimex and
> dtx share:
> 
> tzoffset() returns the offset east of UTC, in minutes. Could we
> avoid arguments about the meaning of timezone if we simply called
> this toffset instead? A toffset returns an offset to a time
> expressed in minutes east of UTC, for whatever reason a dtx
> chooses. (Except that a separate method exists to deal with DST. But
> a dtx subclass writer could choose to bundle the two notions
> together in this method if they really wanted to, I suppose.)

I'd be happy to call this utcoffset().

> tzname() returns a string that names the intended timezone. What
> about the fact that a dtx may have multiple names for its notion of
> an individual timezone? Should this return a tuple, instead of a
> string? Should it be tznames instead of tzname?

No, YAGNI.  (See previous mail.)

> tzisdst() returns 0 if DST is not in effect, or the DST offset if
> DST is in effect. This sounds like a simple truth function, but it
> returns an offset.  Should it be named dstoffset instead? Then we
> would have toffset and dstoffset, which seems to be nicely
> symmetrical.

Except there's nothing in their functionality that requires symmetry.
The UTC offset is required for comparison of time involving diffent
timezones (which includes different DST offsets).  The dst info is
never needed -- *this* is purely informational, in case the
application is interested in the DST status (for which I still haven't
seen a use case, BTW, but which Tim argues is needed from a
"discoverability" perspective).  I'd almost call it dstinfo() except
that would suggest a symmetry with tzinfo() which is also incorrect.

I agree that the name "isdst()" for something returning an int whose
nonzero value has (some) semantics is confusing.

Maybe it should just be called dst()?

I'd also be happy to drop it, based on YAGNI (it's very easy to add in
a later stage since it doesn't affect anything else).

> tzinfo() returns the tzinfo object. This would be renamed to match
> the hook, such as dtx().

I like tzinfo() best.

--Guido van Rossum (home page: http://www.python.org/~guido/)