pytz-2016.7.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 saving time, which you can read more about in the Python Library 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 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 LMT+0020' It is safe for timezones without daylight saving transitions 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 saving time and other timezone transitions. In this example, ``loc_dt`` is set to the instant when daylight saving 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 local times 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 is more easily done, using the standard astimezone method. >>> 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 = utc_dt.astimezone(au_tz) >>> au_dt.strftime(fmt) '2006-03-27 08:34:59 AEDT+1100' >>> utc_dt2 = au_dt.astimezone(utc) >>> utc_dt2.strftime(fmt) '2006-03-26 21:34:59 UTC+0000' >>> utc_dt == utc_dt2 True 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 saving 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 AEDT+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 ignored for most timestamps. It is only used during DST transition ambiguous periods to resulve that ambiguity. >>> 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, instead of 2: