[Python-Dev] Draft PEP for time zone support. (original) (raw)

Lennart Regebro regebro at gmail.com
Tue Dec 11 16:23:37 CET 2012

This PEP is also available on github:

https://github.com/regebro/tz-pep/blob/master/pep-04tz.txt

Text:

PEP: 4?? Title: Time zone support improvements Version: RevisionRevisionRevision Last-Modified: DateDateDate Author: Lennart Regebro <regebro at gmail.com> BDFL-Delegate: Barry Warsaw Status: Draft Type: Standards Track Content-Type: text/x-rst Created: 11-Dec-2012 Post-History: 11-Dec-2012

Abstract

This PEP proposes the implementation of concrete time zone support in the Python standard library, and also improvements to the time zone API to deal with ambiguous time specifications during DST changes.

Proposal

Concrete time zone support

The time zone support in Python has no concrete implementation in the standard library, only a tzinfo baseclass, and since Python 3.2, one concrete time zone: UTC. To properly support time zones you need to include a database over all time zones, both current and historical, including daylight saving changes. But such information changes frequently, so even if we include the last information in a Python release, that information would be outdated just a few months later.

Timezone support has therefore only been available through two third-party modules, pytz and dateutil, both who include and wrap the "zoneinfo" database. This database, also called "tz" or "The Olsen database", is the de-facto standard time zone database over time zones, and it is included in most variants of Unix operating systems, including OS X.

This gives us the opportunity to include only the code that supports the zoneinfo data in the standard library, but by default use the operating systems copy of the data, which typically will be kept updated by the updating mechanism of the operating system or distribution.

For those who have an operating system that does not include the tz database, for example Windows, a distribution containing the latest tz database should also be available at the Python Package Index, so it can be easily installed with the Python packaging tools such as easy_install or pip. This could also be done on Unices that are no longer recieving updates and therefore has an outdated database.

With such a mechanism Python would have full time zone support in the standard library on most platforms, and a simple package installation would provide time zone support on those platforms where the tz database isn't included, such as Windows.

The time zone support will be implemented by a new module called `timezone, based on Stuart Bishop's pytz`` module.

Getting the local time zone

On Unix there is no standard way of finding the name of the time zone that is being used. All the information that is available is the time zone abbreviations, such as EST and PDT, but many of those abbreviations are ambigious and therefore you can't rely on them to figure out which time zone you are located in.

There is however a standard for finding the compiled time zone information since it's located in /etc/localtime. Therefore it is possible to create a local time zone object with the correct time zone information even though you don't know the name of the time zone. A function in datetime should be provided to return the local time zone.

The support for this will be made by integrating Lennart Regebro's tzlocal module into the new timezone module.

Ambiguous times

When changing over from daylight savings time the clock is turned back one hour. This means that the times during that hour happens twice, once without DST and then once with DST. Similarily, when changing to daylight savings time, one hour goes missing.

The current time zone API can not differentiating between the two ambiguous times during a change from DST. For example, in Stockholm the time of 2012-11-28 02:00:00 happens twice, both at UTC 2012-11-28 00:00:00 and also at 2012-11-28 01:00:00.

The current time zone API can not disambiguate this and therefore it's unclear which time should be returned::

# This could be either 00:00 or 01:00 UTC:
>>> dt = datetime(2012, 11, 28, 2, 0, tzinfo=timezone('Europe/Stockholm'))
# But we can not specify which:
>>> dt.astimezone(timezone('UTC'))
datetime.datetime(2012, 11, 28, 1, 0, tzinfo=<UTC>)

pytz solved this problem by adding is_dst parameters to several methods of the tzinfo objects to make it possible to disambiguate times when this is desired.

This PEP proposes to add these is_dst parameters to the relevant methods of the datetime API, and therefore add this functionality directly to datetime. This is likely the hardest part of this PEP as this involves updating the

Implementation API

The new timezone-module

The public API of the new timezone-module contains one new class, one new function and one new exception.

or otherwise use the database in /usr/share/zoneinfo.

If no database is found an UnknownTimeZoneError or subclass thereof will be raised with a message explaining that no zoneinfo database can be found, but that you can install one with the timezonedata package.

can't be found::

 >>> datetime.Timezone('Europe/New_York')
 Traceback (most recent call last):
 ...
 UnknownTimeZoneError: There is no time zone called 'Europe/New_York'

Changes in the datetime-module

A new is_dst parameter is added to several of the tzinfo methods to handle time ambiguity during DST changeovers.

The is_dst parameter can be True (default), False, or None.

True will specify that the given datetime should be interpreted as happening during daylight savings time, ie that the time specified is before the change from DST.

False will specify that the given datetime should be interpreted as not happening during daylight savings time, ie that the time specified is after the change from DST.

None will raise an AmbiguousTimeError exception if the time specified was during a DST change over. It will also raise a NonExistentTimeError if a time is specified during the "missing time" in a change to DST.

There are also two new exceptions:

are ambigious while setting is_dst to None::

>>> datetime(2012, 11, 28, 2, 0,

tzinfo=timezone('Europe/Stockholm'), is_dst=None) >>> Traceback (most recent call last): ... AmbiguousTimeError: 2012-10-28 02:00:00 is ambiguous in time zone Europe/Stockholm

are ambigious while setting is_dst to None::

>>> datetime(2012, 3, 25, 2, 0,

tzinfo=timezone('Europe/Stockholm'), is_dst=None) >>> Traceback (most recent call last): ... NonExistentTimeError: 2012-03-25 02:00:00 does not exist in time zone Europe/Stockholm

The timezonedata-package

The zoneinfo database will be packaged for easy installation with easy_install/pip/buildout. This package will not install any Python code, and will not contain any Python code except that which is needed for installation.

Differences from the pytz API

Discussion

Should the windows installer include the data package?

It has been suggested that the Windows installer should include the data package. This would mean that an explicit installation no longer would be needed on Windows. On the other hand, that would mean that many using Windows would not be aware that the database quickly becomes outdated and would not keep it updated.

Resources

Copyright

This document has been placed in the public domain.

More information about the Python-Dev mailing list