Python time zones

I have not maintened this package for several years and I know it to be bogus. So it's probably not a good idea to use it.


download version 0.2 (~20k)


time zone data (~52k)

Python 2.3 defines a new datetime module which provide some great tools for handling date and time operation. The datetime module define the tzinfo protocol for handling time zone management but doesn't provide any concrete implementation by itself. The goal of this tz package is to provide a set of concrete tzinfo implementation.

Right now the package support only the tzinfo public domain database. The tzinfo database is used by Linux, xxxBSD and MacosX (and probably many other Unix flavors).

Introduction

Time zone and daylight saving time parameters are used to do conversions between local time and universal (UTC) time.
Time zones and daylight saving time definition are a geopolitical problem. That mean that theses parameters depend both of the location and the date considered and that we can't find an universal rules to do the conversion. So we need to rely on a database to get this kind of informations.
You can find some introduction material about time zones at http://www.mindspring.com/~gwil/tconcept.html

The goal of the tz package is to provide a unified API for the various time zone database used by the platforms able to run Python.

Tutorial

The tz package is mostly intended to be used with datetime module objects. The most common way is to create a tzinfo object by calling the the tz.timezone function with a valid timezone name. There isn't a standardized way to name a timezone. For the tzfile backend, this name is simply the relative path of time-zone files in the zoneinfo database. For some time zone you can use the 3 letters code (eg 'CET') for other you can't (eg 'JST' doesn't work and you will have to use 'Asia/Tokyo'). If you have several backends defined, the tz.timezone object will return the first backend instance wich won't raise a ValueError. 
>>> import datetime, tz
>>> T = tz.timezone("Europe/Amsterdam")
>>> dt1 = datetime.datetimetz(2003,1,1,12,0,0,tzinfo=T)
>>> print dt1
2003-01-01 12:00:00+01:00
>>> print dt1.utcoffset()
1:00:00
>>> print dt1.tzname()
CET
>>> U = tz.timezone("America/Buenos_Aires")
>>> dt2 = datetime.datetimetz(2003,1,1,12,0,0,tzinfo=U)
>>> print dt2
2003-01-01 12:00:00-03:00
>>> print dt2.utcoffset()
-1 day, 21:00:00
>>> print dt2.tzname()
ART
>>> print dt2-dt1
4:00:00

You can also use the local time zone 

>>> import tz
>>> l = tz.timezone("localtime")
Or the obvious UTC time zone 
>>> import tz
>>> utc = tz.timezone("UTC")

Reference

tz package

Generic interface for time-zone databases. It is dependent of backends for the actual implementation.
When tz is imported it will look for the available backends. If no backend is available, raise an ImportError exception.

function timezone(name)
Return a timezone object or raise a value error if the name argument isn't a valid timezone name for any backend available.

The timezone objects define the several methods required by the tzinfo protocol:

method utcoffset(dt)
return offset of local time from UTC

method tzname(dt)
return the timezone name corresponding to the datetime represented by dt.

method dst(dt)
return the daylight saving time offset.

See the datetime module documentation for more informations.

tz.tzfile module

Interface with the public domain timezone database: http://www.twinsun.com/tz/tz-link.htm also known as the Olson database.

This database is used by many unixes flavors, so if you use a computer with an Unix os, there are great chances that the database is already installed in your system. If this is not the case (or if you are using an other os) the package will install a database extract. It contain a rather concequent subset of the database: the rules from 1970 for all the Olson files except 'backward', 'etcetera', 'leapseconds', 'pacificnew', 'solar87', 'solar88' and 'solar89', 'factory' and 'systemv', since these don't really provide any useful timezones.

Note that the installer won't be able to detect existing database if they are neither in the /usr/share/zoneinfo nor in the /usr/lib/zoneinfo directory. If your database is installed somewhere else, you will have to set the TZDIR environment variable or to provide the --tzdir option, to get it detected.

The module provide a timezone object witch act as a wrapper around a tzfile. This object provide all the methods defined by tzinfo and the following one:

method rulesrange(mini, maxi)
return the rules used to compute the gmt dates between min and max as tuple(local transition date, offset in minutes, zone abreviation, dst flag).

Time zones are named from the continent they belong to and by the name of the main town in the time zone.

This table provide some time zone samples. A text in the comment column mean that several time zone can apply to the country.
Code Country TZ name Comments
AR Argentina America/Cordoba most locations
AU Australia Australia/Sydney New South Wales - most locations
BJ Benin Africa/Porto-Novo
CL Chile America/Santiago most locations
FR France Europe/Paris
NL Netherlands Europe/Amsterdam
NP Nepal Asia/Katmandu
NZ New Zealand Pacific/Auckland most locations
TH Thailand Asia/Bangkok
US United States America/New_York Eastern Time
YE Yemen Asia/Aden
This is only a small extract since the database contain approximatively 350 time zone entries.

tz.utctz module

The database installed by the package miss some goodies such as a localtime time zone or an UTC time zone. This module provide both of them.
TZ name Comments
localtime The time zone used by your computer
UTC Universal standard time
GMT alias for UTC timezone