[docs] "sane" tzinfo subclasses

Paul Koning paulkoning at comcast.net
Mon Oct 3 18:39:17 CEST 2011

On Sep 28, 2011, at 7:49 PM, Senthil Kumaran wrote:

> On Sun, Sep 18, 2011 at 09:04:16PM -0400, Paul Koning wrote:
>> Gentlepeople,
>> Section 8.1.6 of the library manual talks about
>> utcoffset(dt)-dst(dt) as the "standard offset" and says that this
>> should not depend on the date or time but only on the location.
> What would be good note to add to explain that? IIRC, someone at the
> top when dealing with datetime and timezones Python docs already
> mentions that it cannot be relied up completely, because timezone
> rules changes sometimes due to politics of the land.

I think the documentation is wrong here.  I did a simple test (using the pytz module which implements the Olson timezone database), using datetime.astimezone() to change from US Eastern time to Venezuela time.  Venezuela changed its standard offset from -4:00 to -4:30 in 2007.

The answer is that it works correctly -- you can see this by doing the experiment once with a date in 2006, and once with a date in a later year (like 2011).

So I think what's needed is to delete this entire block of text from the description of the tzinfo.dst method:

An instance tz of a tzinfo subclass that models both standard and daylight times must be consistent in this sense:
tz.utcoffset(dt) - tz.dst(dt)
mustreturnthesameresultforeverydatetimedtwithdt.tzinfo == tzForsanetzinfosubclasses, this expression yields the time zone’s “standard offset”, which should not depend on the date or the time, but only on geographic location. The implementation of datetime.astimezone() relies on this, but cannot detect violations; it’s the programmer’s responsibility to ensure it. If a tzinfo subclass cannot guarantee this, it may be able to override the default implementation of tzinfo.fromutc() to work correctly with astimezone() regardless.

because it is not true -- astimezone() works right.

It might also be useful to add to the description of the tzinfo.utcoffset() method to point out that the examples given are simplified and apply only if the base offset is indeed constant, which is true for some timezones (like US Eastern) but not others (like Venezuela).  


More information about the docs mailing list