matplotlib-0.91.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.3 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 (over 540) of the Olson timezones are supported [*]_. Note that 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). This cannot be resolved without modifying the Python datetime implementation. However, these tzinfo classes provide a normalize() method which allows you to correct these values. Installation ~~~~~~~~~~~~ This is a standard Python distutils distribution. To install the package, run the following command as an administrative user:: python setup.py install Example & Usage ~~~~~~~~~~~~~~~ >>> 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' >>> fmt = '%Y-%m-%d %H:%M:%S %Z%z' 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 also take shortcuts when dealing with the UTC side of timezone conversions. Normalize and localize are not really necessary because 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' 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:00am the clock is turned back 1 hour and 01:00 happens again (this time 01:00 EST) In fact, every instant between 01:00 and 02:00 occurs twice. This means that if you try and create a time in the US/Eastern timezone using the standard datetime syntax, there is no way to specify if you meant before of after the end-of-daylight-savings-time transition. >>> loc_dt = datetime(2002, 10, 27, 1, 30, 00, tzinfo=eastern) >>> loc_dt.strftime(fmt) '2002-10-27 01:30:00 EST-0500' 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 does not matter. However, if you are trying to schedule meetings with people in different timezones or analyze log files it is not acceptable. The best and simplest solution is to stick with using UTC. The pytz package encourages using UTC for internal timezone representation by including a special UTC implementation based on the standard Python reference implementation in the Python documentation. This timezone unpickles to be the same instance, and pickles to a relatively small size. The UTC implementation can be obtained as pytz.utc, pytz.UTC, or pytz.timezone('UTC'). Note that this instance is not the same instance (or implementation) as other timezones with the same meaning (GMT, Greenwich, Universal, etc.). >>> import pickle, pytz >>> dt = datetime(2005, 3, 1, 14, 13, 21, tzinfo=utc) >>> naive = dt.replace(tzinfo=None) >>> p = pickle.dumps(dt, 1) >>> naive_p = pickle.dumps(naive, 1) >>> len(p), len(naive_p), len(p) - len(naive_p) (60, 43, 17) >>> new = pickle.loads(p) >>> new == dt True >>> new is dt False >>> new.tzinfo is dt.tzinfo True >>> pytz.utc is pytz.UTC is pytz.timezone('UTC') True >>> utc is pytz.timezone('GMT') False If you insist on working with local times, this library provides a facility for constructing them almost unambiguously. >>> loc_dt = datetime(2002, 10, 27, 1, 30, 00) >>> est_dt = eastern.localize(loc_dt, is_dst=True) >>> edt_dt = eastern.localize(loc_dt, is_dst=False) >>> print est_dt.strftime(fmt), '/', edt_dt.strftime(fmt) 2002-10-27 01:30:00 EDT-0400 / 2002-10-27 01:30:00 EST-0500 Note that although this handles many cases, it is still not possible to handle all. In cases where countries change their timezone definitions, cases like the end-of-daylight-savings-time occur with no way of resolving the ambiguity. For example, in 1915 Warsaw switched from Warsaw time to Central European time. So at the stroke of midnight on August 4th 1915 the clocks were wound back 24 minutes creating a ambiguous time period that cannot be specified without referring to the timezone abbreviation or the actual UTC offset. The 'Standard' Python way of handling all these ambiguities is not to, such as demonstrated in this example using the US/Eastern timezone definition from the Python documentation (Note that this implementation only works for dates between 1987 and 2006 - it is included for tests only!): >>> from pytz.reference import Eastern # pytz.reference only for tests >>> dt = datetime(2002, 10, 27, 0, 30, tzinfo=Eastern) >>> str(dt) '2002-10-27 00:30:00-04:00' >>> str(dt + timedelta(hours=1)) '2002-10-27 01:30:00-05:00' >>> str(dt + timedelta(hours=2)) '2002-10-27 02:30:00-05:00' >>> str(dt + timedelta(hours=3)) '2002-10-27 03:30:00-05:00' Notice the first two results? At first glance you might think they are correct, but taking the UTC offset into account you find that they are actually two hours appart instead of the 1 hour we asked for. >>> from pytz.reference import UT