matplotlib-1.1.1.tar.gz

pytz - World Timezone Definitions for Python ============================================ :Author: Stuart Bishop <stuart@stuartbishop.net> Introduction ~~~~~~~~~~~~ pytz brings the Olson tz database into Python. This library allows accurate and cross platform timezone calculations using Python 2.4 or higher. It also solves the issue of ambiguous times at the end of daylight savings, which you can read more about in the Python Library Reference (``datetime.tzinfo``). Amost all of the Olson timezones are supported. Note that 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 results 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. Unfortunatly these issues cannot be resolved without modifying the Python datetime implementation. 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 an administrative user:: python setup.py install If you are installing using setuptools, you don't even need to download anything as the latest version will be downloaded for you from 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 ----------------------------------- >>> from datetime import datetime, timedelta >>> from pytz import timezone >>> import pytz >>> utc = pytz.utc >>> utc.zone 'UTC' >>> eastern = timezone('US/Eastern') >>> eastern.zone 'US/Eastern' >>> amsterdam = timezone('Europe/Amsterdam') >>> fmt = '%Y-%m-%d %H:%M:%S %Z%z' This library only supports two ways of building a localized time. The first is to use the ``localize()`` method provided by the pytz library. This is used to localize a naive datetime (datetime with no timezone information): >>> loc_dt = eastern.localize(datetime(2002, 10, 27, 6, 0, 0)) >>> print(loc_dt.strftime(fmt)) 2002-10-27 06:00:00 EST-0500 The second way of building a localized time is by converting an existing localized time using the standard ``astimezone()`` method: >>> ams_dt = loc_dt.astimezone(amsterdam) >>> ams_dt.strftime(fmt) '2002-10-27 12:00:00 CET+0100' Unfortunately using the tzinfo argument of the standard datetime constructors ''does not work'' with pytz for many timezones. >>> datetime(2002, 10, 27, 12, 0, 0, tzinfo=amsterdam).strftime(fmt) '2002-10-27 12:00:00 AMT+0020' It is safe for timezones without daylight savings trasitions though, such as UTC: >>> datetime(2002, 10, 27, 12, 0, 0, tzinfo=pytz.utc).strftime(fmt) '2002-10-27 12:00:00 UTC+0000' The preferred way of dealing with times is to always work in UTC, converting to localtime only when generating output to be read by humans. >>> utc_dt = datetime(2002, 10, 27, 6, 0, 0, tzinfo=utc) >>> loc_dt = utc_dt.astimezone(eastern) >>> loc_dt.strftime(fmt) '2002-10-27 01:00:00 EST-0500' This library also allows you to do date arithmetic using local times, although it is more complicated than working in UTC as you need to use the ``normalize()`` method to handle daylight savings time and other timezone transitions. In this example, ``loc_dt`` is set to the instant when daylight savings time ends in the US/Eastern timezone. >>> before = loc_dt - timedelta(minutes=10) >>> before.strftime(fmt) '2002-10-27 00:50:00 EST-0500' >>> eastern.normalize(before).strftime(fmt) '2002-10-27 01:50:00 EDT-0400' >>> after = eastern.normalize(before + timedelta(minutes=20)) >>> after.strftime(fmt) '2002-10-27 01:10:00 EST-0500' Creating localtimes is also tricky, and the reason why working with local times is not recommended. Unfortunately, you cannot just pass a ``tzinfo`` argument when constructing a datetime (see the next section for more details) >>> dt = datetime(2002, 10, 27, 1, 30, 0) >>> dt1 = eastern.localize(dt, is_dst=True) >>> dt1.strftime(fmt) '2002-10-27 01:30:00 EDT-0400' >>> dt2 = eastern.localize(dt, is_dst=False) >>> dt2.strftime(fmt) '2002-10-27 01:30:00 EST-0500' Converting between timezones also needs special attention. This also needs to use the ``normalize()`` method to ensure the conversion is correct. >>> utc_dt = utc.localize(datetime.utcfromtimestamp(1143408899)) >>> utc_dt.strftime(fmt) '2006-03-26 21:34:59 UTC+0000' >>> au_tz = timezone('Australia/Sydney') >>> au_dt = au_tz.normalize(utc_dt.astimezone(au_tz)) >>> au_dt.strftime(fmt) '2006-03-27 08:34:59 EST+1100' >>> utc_dt2 = utc.normalize(au_dt.astimezone(utc)) >>> utc_dt2.strftime(fmt) '2006-03-26 21:34:59 UTC+0000' You can take shortcuts when dealing with the UTC side of timezone conversions. ``normalize()`` and ``localize()`` are not really necessary when there are no daylight savings time transitions to deal with. >>> utc_dt = datetime.utcfromtimestamp(1143408899).replace(tzinfo=utc) >>> utc_dt.strftime(fmt) '2006-03-26 21:34:59 UTC+0000' >>> au_tz = timezone('Australia/Sydney') >>> au_dt = au_tz.normalize(utc_dt.astimezone(au_tz)) >>> au_dt.strftime(fmt) '2006-03-27 08:34:59 EST+1100' >>> utc_dt2 = au_dt.astimezone(utc) >>> utc_dt2.strftime(fmt) '2006-03-26 21:34:59 UTC+0000' ``tzinfo`` API -------------- The ``tzinfo`` instances returned by the ``timezone()`` function have been extended to cope with ambiguous times by adding an ``is_dst`` parameter to the ``utcoffset()``, ``dst()`` && ``tzname()`` methods. >>> tz = timezone('America/St_Johns') >>> normal = datetime(2009, 9, 1) >>> ambiguous = datetime(2009, 10, 31, 23, 30) the ``is_dst`` parameter is ignormed for most timestamps, but is used to resolve the ambiguity during ambiguous periods caused to DST transitions. >>> tz.utcoffset(normal, is_dst=True) datetime.timedelta(-1, 77400) >>> tz.dst(normal, is_dst=True) datetime.timedelta(0, 3600) >>> tz.tzname(normal, is_dst=True) 'NDT' >>> tz.utcoffset(ambiguous, is_dst=True) datetime.timedelta(-1, 77400) >>> tz.dst(ambiguous, is_dst=True) datetime.timedelta(0, 3600) >>> tz.tzname(ambiguous, is_dst=True) 'NDT' >>> tz.utcoffset(normal, is_dst=False) datetime.timedelta(-1, 77400) >>> tz.dst(normal, is_dst=False) datetime.timedelta(0, 3600) >>> tz.tzname(normal, is_dst=False) 'NDT' >>> tz.utcoffset(ambiguous, is_dst=False) datetime.timedelta(-1, 73800) >>> tz.dst(ambiguous, is_dst=False) datetime.timedelta(0) >>> tz.tzname(ambiguous, is_dst=False) 'NST' If ``is_dst`` is not specified, ambiguous timestamps will raise an ``pytz.exceptions.AmbiguousTimeError`` exception. >>> tz.utcoffset(normal) datetime.timedelta(-1, 77400) >>> tz.dst(normal) datetime.timedelta(0, 3600) >>> tz.tzname(normal) 'NDT' >>> import pytz.exceptions >>> try: ... tz.utcoffset(ambiguous) ... except pytz.exceptions.AmbiguousTimeError: ... print('pytz.exceptions.AmbiguousTimeError: %s' % ambiguous) pytz.exceptions.AmbiguousTimeError: 2009-10-31 23:30:00 >>> try: ... tz.dst(ambiguous) ... except pytz.exceptions.AmbiguousTimeError: ... print('pytz.exceptions.AmbiguousTimeError: %s' % ambiguous) pytz.exceptions.AmbiguousTimeError: 2009-10-31 23:30:00 >>> try: ... tz.tzname(ambiguous) ... except pytz.exceptions.AmbiguousTimeError: ... print('pytz.exceptions.AmbiguousTimeError: %s' % ambiguous) pytz.exceptions.AmbiguousTimeError: 2009-10-31 23:30:00 Problems with Localtime ~~~~~~~~~~~~~~~~~~~~~~~ The major problem we have to deal with is that certain datetimes may occur twice in a year. For example, in the US/Eastern timezone on the last Sunday morning in October, the following sequence happens: - 01:00 EDT occurs - 1 hour later, ins