Project description

pytz brings the Olson tz database into Python. This library allowsaccurate and cross platform timezone calculations using Python 2.4or higher. It also solves the issue of ambiguous times at the endof daylight saving time, which you can read more about in the PythonLibrary Reference (``datetime.tzinfo``).

Almost all of the Olson timezones are supported.

.. note::

This library differs from the documented Python API for tzinfo implementations; if you want to create local wallclock times you need to use the ``localize()`` method documented in this document. In addition, if you perform date arithmetic on local times that cross DST boundaries, the result may be in an incorrect timezone (ie. subtract 1 minute from 2002-10-27 1:00 EST and you get 2002-10-27 0:59 EST instead of the correct 2002-10-27 1:59 EDT). A ``normalize()`` method is provided to correct this. Unfortunately these issues cannot be resolved without modifying the Python datetime implementation (see PEP-431).

Installation~~~~~~~~~~~~

This package can either be installed from a .egg file using setuptools,or from the tarball using the standard Python distutils.

If you are installing from a tarball, run the following command as anadministrative user::

python setup.py install

If you are installing using setuptools, you don't even need to downloadanything as the latest version will be downloaded for youfrom the Python package index::

easy_install --upgrade pytz

If you already have the .egg file, you can use that too::

easy_install pytz-2008g-py2.6.egg

Example & Usage~~~~~~~~~~~~~~~

Localized times and date arithmetic-----------------------------------

This library only supports two ways of building a localized time. Thefirst is to use the ``localize()`` method provided by the pytz library.This is used to localize a naive datetime (datetime with no timezoneinformation):

This library also allows you to do date arithmetic using localtimes, although it is more complicated than working in UTC as youneed to use the ``normalize()`` method to handle daylight saving timeand other timezone transitions. In this example, ``loc_dt`` is setto the instant when daylight saving time ends in the US/Easterntimezone.

Creating local times is also tricky, and the reason why working withlocal times is not recommended. Unfortunately, you cannot just passa ``tzinfo`` argument when constructing a datetime (see the nextsection for more details)

The ``tzinfo`` instances returned by the ``timezone()`` function havebeen extended to cope with ambiguous times by adding an ``is_dst``parameter to the ``utcoffset()``, ``dst()`` && ``tzname()`` methods.

In fact, every instant between 01:00 and 02:00 occurs twice. This meansthat if you try and create a time in the 'US/Eastern' timezonethe standard datetime syntax, there is no way to specify if you meantbefore of after the end-of-daylight-saving-time transition. Using thepytz custom syntax, the best you can do is make an educated guess:

As you can see, the system has chosen one for you and there is a 50%chance of it being out by one hour. For some applications, this doesnot matter. However, if you are trying to schedule meetings with peoplein different timezones or analyze log files it is not acceptable.

The best and simplest solution is to stick with using UTC. The pytzpackage encourages using UTC for internal timezone representation byincluding a special UTC implementation based on the standard Pythonreference implementation in the Python documentation.

The UTC timezone unpickles to be the same instance, and pickles to asmaller size than other pytz tzinfo instances. The UTC implementationcan be obtained as pytz.utc, pytz.UTC, or pytz.timezone('UTC').

Note that some other timezones are commonly thought of as the same (GMT,Greenwich, Universal, etc.). The definition of UTC is distinct from theseother timezones, and they are not equivalent. For this reason, they willnot compare the same in Python.

>>> utc == pytz.timezone('GMT')False

See the section `What is UTC`_, below.

If you insist on working with local times, this library provides afacility for constructing them unambiguously:

A special case is where countries change their timezone definitionswith no daylight savings time switch. For example, in 1915 Warsawswitched from Warsaw time to Central European time with no daylight savingstransition. So at the stroke of midnight on August 5th 1915 the clockswere wound back 24 minutes creating an ambiguous time period that cannotbe specified without referring to the timezone abbreviation or theactual UTC offset. In this case midnight happened twice, neither timeduring a daylight saving time period. pytz handles this transition bytreating the ambiguous period before the switch as daylight savingstime, and the ambiguous period after as standard time.

The standard Python way of handling all these ambiguities is not tohandle them, such as demonstrated in this example using the US/Easterntimezone definition from the Python documentation (Note that thisimplementation only works for dates between 1987 and 2006 - it isincluded for tests only!):

Notice the first two results? At first glance you might think they arecorrect, but taking the UTC offset into account you find that they areactually two hours appart instead of the 1 hour we asked for.

A mechanism is provided to access the timezones commonly in usefor a particular country, looked up using the ISO 3166 country code.It returns a list of strings that can be used to retrieve the relevanttzinfo instance using ``pytz.timezone()``:

The Olson database comes with a ISO 3166 country code to English countryname mapping that pytz exposes as a dictionary:

>>> print(pytz.country_names['nz'])New Zealand

What is UTC~~~~~~~~~~~

'UTC' is `Coordinated Universal Time`_. It is a successor to, but distinctfrom, Greenwich Mean Time (GMT) and the various definitions of UniversalTime. UTC is now the worldwide standard for regulating clocks and timemeasurement.

All other timezones are defined relative to UTC, and include offsets likeUTC+0800 - hours to add or subtract from UTC to derive the local time. Nodaylight saving time occurs in UTC, making it a useful timezone to performdate arithmetic without worrying about the confusion and ambiguities causedby daylight saving time transitions, your country changing its timezone, ormobile computers that roam through multiple timezones.

``common_timezones`` is a list of useful, current timezones. It doesn'tcontain deprecated zones or historical zones, except for a few I'vedeemed in common usage, such as US/Eastern (open a bug report if youthink other timezones are deserving of being included here). It is alsoa sequence of strings.

This code is also available as part of Zope 3 under the Zope PublicLicense, Version 2.1 (ZPL).

I'm happy to relicense this code if necessary for inclusion in otheropen source projects.

Latest Versions~~~~~~~~~~~~~~~

This package will be updated after releases of the Olson timezonedatabase. The latest version can be downloaded from the `Python PackageIndex <http://pypi.python.org/pypi/pytz/>`_. The code that is usedto generate this distribution is hosted on launchpad.net and availableusing the `Bazaar version control system <http://bazaar-vcs.org>`_using::

bzr branch lp:pytz

Announcements of new releases are made on`Launchpad <https://launchpad.net/pytz>`_, and the`Atom feed <http://feeds.launchpad.net/pytz/announcements.atom>`_hosted there.

Bugs, Feature Requests & Patches~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Bugs can be reported using `Launchpad <https://bugs.launchpad.net/pytz>`_.

Issues & Limitations~~~~~~~~~~~~~~~~~~~~

- Offsets from UTC are rounded to the nearest whole minute, so timezones such as Europe/Amsterdam pre 1937 will be up to 30 seconds out. This is a limitation of the Python datetime library.

- If you think a timezone definition is incorrect, I probably can't fix it. pytz is a direct translation of the Olson timezone database, and changes to the timezone definitions need to be made to this source. If you find errors they should be reported to the time zone mailing list, linked from http://www.iana.org/time-zones.

Further Reading~~~~~~~~~~~~~~~

More info than you want to know about timezones:http://www.twinsun.com/tz/tz-link.htm