15
15
Amost all (over 540) of the Olson timezones are supported [*]_.
17
Note that if you perform date arithmetic on local times that cross
18
DST boundaries, the results may be in an incorrect timezone (ie.
19
subtract 1 minute from 2002-10-27 1:00 EST and you get 2002-10-27
20
0:59 EST instead of the correct 2002-10-27 1:59 EDT). This cannot
21
be resolved without modifying the Python datetime implementation.
22
However, these tzinfo classes provide a normalize() method which
23
allows you to correct these values.
17
Note that this library differs from the documented Python API for
18
tzinfo implementations; if you want to create local wallclock
19
times you need to use the localize() method documented in this
20
document. In addition, if you perform date arithmetic on local
21
times that cross DST boundaries, the results may be in an incorrect
22
timezone (ie. subtract 1 minute from 2002-10-27 1:00 EST and you get
23
2002-10-27 0:59 EST instead of the correct 2002-10-27 1:59 EDT). A
24
normalize() method is provided to correct this. Unfortunatly these
25
issues cannot be resolved without modifying the Python datetime
29
This is a standard Python distutils distribution. To install the
30
package, run the following command as an administrative user::
32
This package can either be installed from a .egg file using setuptools,
33
or from the tarball using the standard Python distutils.
35
If you are installing from a tarball, run the following command as an
32
38
python setup.py install
40
If you are installing using setuptools, you don't even need to download
41
anything as the latest version will be downloaded for you
42
from the Python package index::
44
easy_install --upgrade pytz
46
If you already have the .egg file, you can use that too::
48
easy_install pytz-2008g-py2.6.egg
44
60
>>> eastern = timezone('US/Eastern')
63
>>> amsterdam = timezone('Europe/Amsterdam')
47
64
>>> fmt = '%Y-%m-%d %H:%M:%S %Z%z'
66
This library only supports two ways of building a localized time. The
67
first is to use the .localize() method provided by the pytz library.
68
This is used to localize a naive datetime (datetime with no timezone
71
>>> loc_dt = eastern.localize(datetime(2002, 10, 27, 6, 0, 0))
72
>>> print loc_dt.strftime(fmt)
73
2002-10-27 06:00:00 EST-0500
75
The second way of building a localized time is by converting an existing
76
localized time using the standard .astimezone() method:
78
>>> ams_dt = loc_dt.astimezone(amsterdam)
79
>>> ams_dt.strftime(fmt)
80
'2002-10-27 12:00:00 CET+0100'
82
Unfortunately using the tzinfo argument of the standard datetime
83
constructors ''does not work'' with pytz for many timezones.
85
>>> datetime(2002, 10, 27, 12, 0, 0, tzinfo=amsterdam).strftime(fmt)
86
'2002-10-27 12:00:00 AMT+0020'
88
It is safe for timezones without daylight savings trasitions though, such
91
>>> datetime(2002, 10, 27, 12, 0, 0, tzinfo=pytz.utc).strftime(fmt)
92
'2002-10-27 12:00:00 UTC+0000'
49
94
The preferred way of dealing with times is to always work in UTC,
50
95
converting to localtime only when generating output to be read
140
185
not matter. However, if you are trying to schedule meetings with people
141
186
in different timezones or analyze log files it is not acceptable.
143
The best and simplest solution is to stick with using UTC. The pytz package
144
encourages using UTC for internal timezone representation by including a
145
special UTC implementation based on the standard Python reference
146
implementation in the Python documentation. This timezone unpickles to be
147
the same instance, and pickles to a relatively small size. The UTC
148
implementation can be obtained as pytz.utc, pytz.UTC, or
149
pytz.timezone('UTC'). Note that this instance is not the same
150
instance (or implementation) as other timezones with the same meaning
151
(GMT, Greenwich, Universal, etc.).
188
The best and simplest solution is to stick with using UTC. The pytz
189
package encourages using UTC for internal timezone representation by
190
including a special UTC implementation based on the standard Python
191
reference implementation in the Python documentation. This timezone
192
unpickles to be the same instance, and pickles to a relatively small
193
size. The UTC implementation can be obtained as pytz.utc, pytz.UTC,
194
or pytz.timezone('UTC').
153
196
>>> import pickle, pytz
154
197
>>> dt = datetime(2005, 3, 1, 14, 13, 21, tzinfo=utc)
167
210
>>> pytz.utc is pytz.UTC is pytz.timezone('UTC')
213
Note that this instance is not the same instance (or implementation) as
214
other timezones with the same meaning (GMT, Greenwich, Universal, etc.).
169
216
>>> utc is pytz.timezone('GMT')
172
219
If you insist on working with local times, this library provides a
173
facility for constructing them almost unambiguously.
220
facility for constructing them unambiguously:
175
222
>>> loc_dt = datetime(2002, 10, 27, 1, 30, 00)
176
223
>>> est_dt = eastern.localize(loc_dt, is_dst=True)
178
225
>>> print est_dt.strftime(fmt), '/', edt_dt.strftime(fmt)
179
226
2002-10-27 01:30:00 EDT-0400 / 2002-10-27 01:30:00 EST-0500
181
Note that although this handles many cases, it is still not possible
228
If you pass None as the is_dst flag to localize(), pytz will refuse to
229
guess and raise exceptions if you try to build ambiguous or non-existent
232
For example, 1:30am on 27th Oct 2002 happened twice in the US/Eastern
233
timezone when the clocks where put back at the end of Daylight Savings
236
>>> eastern.localize(datetime(2002, 10, 27, 1, 30, 00), is_dst=None)
237
Traceback (most recent call last):
239
AmbiguousTimeError: 2002-10-27 01:30:00
241
Similarly, 2:30am on 7th April 2002 never happened at all in the
242
US/Eastern timezone, as the clock where put forward at 2:00am skipping
245
>>> eastern.localize(datetime(2002, 4, 7, 2, 30, 00), is_dst=None)
246
Traceback (most recent call last):
248
NonExistentTimeError: 2002-04-07 02:30:00
250
Both of these exceptions share a common base class to make error handling
253
>>> isinstance(pytz.AmbiguousTimeError(), pytz.InvalidTimeError)
255
>>> isinstance(pytz.NonExistentTimeError(), pytz.InvalidTimeError)
258
Although localize() handles many cases, it is still not possible
182
259
to handle all. In cases where countries change their timezone definitions,
183
260
cases like the end-of-daylight-savings-time occur with no way of resolving
184
261
the ambiguity. For example, in 1915 Warsaw switched from Warsaw time to
185
Central European time. So at the stroke of midnight on August 4th 1915
186
the clocks were wound back 24 minutes creating a ambiguous time period
262
Central European time. So at the stroke of midnight on August 5th 1915
263
the clocks were wound back 24 minutes creating an ambiguous time period
187
264
that cannot be specified without referring to the timezone abbreviation
188
or the actual UTC offset.
265
or the actual UTC offset. In this case midnight happened twice, neither
266
time during a daylight savings time period:
268
>>> warsaw = pytz.timezone('Europe/Warsaw')
269
>>> loc_dt1 = warsaw.localize(datetime(1915, 8, 4, 23, 59, 59), is_dst=False)
270
>>> loc_dt1.strftime(fmt)
271
'1915-08-04 23:59:59 WMT+0124'
272
>>> loc_dt2 = warsaw.localize(datetime(1915, 8, 5, 00, 00, 00), is_dst=False)
273
>>> loc_dt2.strftime(fmt)
274
'1915-08-05 00:00:00 CET+0100'
275
>>> str(loc_dt2 - loc_dt1)
278
The only way of creating a time during the missing 24 minutes is converting
279
from another time - because neither of the timezones involved where in
280
daylight savings mode the API simply provides no way to express it:
282
>>> utc_dt = datetime(1915, 8, 4, 22, 36, tzinfo=pytz.utc)
283
>>> utc_dt.astimezone(warsaw).strftime(fmt)
284
'1915-08-04 23:36:00 CET+0100'
190
286
The 'Standard' Python way of handling all these ambiguities is not to,
191
287
such as demonstrated in this example using the US/Eastern timezone
214
310
'2002-10-27 06:30:00+00:00'
316
A mechanism is provided to access the timezones commonly in use
317
for a particular country, looked up using the ISO 3166 country code.
318
It returns a list of strings that can be used to retrieve the relevant
319
tzinfo instance using `pytz.timezone()`:
321
>>> pytz.country_timezones['nz']
322
['Pacific/Auckland', 'Pacific/Chatham']
324
The Olson database comes with a ISO 3166 country code to English country
325
name mapping that pytz exposes as a dictionary:
327
>>> pytz.country_names['nz']
220
`UTC` is Universal Time, formerly known as Greenwich Mean Time or GMT.
221
All other timezones are given as offsets from UTC. No daylight savings
222
time occurs in UTC, making it a useful timezone to perform date arithmetic
223
without worrying about the confusion and ambiguities caused by daylight
224
savings time transitions, your country changing its timezone, or mobile
225
computers that move roam through multiple timezones.
334
`UTC` is Universal Time, also known as Greenwich Mean Time or GMT
335
in the United Kingdom. All other timezones are given as offsets from
336
UTC. No daylight savings time occurs in UTC, making it a useful timezone
337
to perform date arithmetic without worrying about the confusion and
338
ambiguities caused by daylight savings time transitions, your country
339
changing its timezone, or mobile computers that move roam through
241
356
`common_timezones` is a list of useful, current timezones. It doesn't
242
contain deprecated zones or historical zones. It is also a sequence of
357
contain deprecated zones or historical zones, except for a few I've
358
deemed in common usage, such as US/Eastern (open a bug report if you
359
think other timezones are deserving of being included here).It is also
360
a sequence of strings.
245
362
>>> from pytz import common_timezones
246
363
>>> len(common_timezones) < len(all_timezones)
248
365
>>> 'Etc/Greenwich' in common_timezones
367
>>> 'US/Eastern' in common_timezones
369
>>> 'Australia/Melbourne' in common_timezones
371
>>> 'US/Pacific-New' in all_timezones
373
>>> 'US/Pacific-New' in common_timezones
376
Both common_timezones and all_timezones are alphabetically sorted:
378
>>> common_timezones_dupe = common_timezones[:]
379
>>> common_timezones_dupe.sort()
380
>>> common_timezones == common_timezones_dupe
382
>>> all_timezones_dupe = all_timezones[:]
383
>>> all_timezones_dupe.sort()
384
>>> all_timezones == all_timezones_dupe
387
`all_timezones` and `common_timezones` are also available as sets.
389
>>> from pytz import all_timezones_set, common_timezones_set
390
>>> 'US/Eastern' in all_timezones_set
392
>>> 'US/Eastern' in common_timezones_set
394
>>> 'Australia/Victoria' in common_timezones_set
251
397
You can also retrieve lists of timezones used by particular countries
252
398
using the `country_timezones()` method. It requires an ISO-3166 two letter
275
This package will be updated after releases of the Olson timezone database.
276
The latest version can be downloaded from the Python Cheeseshop_ or
277
Sourceforge_. The code that is used to generate this distribution is
278
available using the Bazaar_ revision control system using::
280
bzr branch http://bazaar.launchpad.net/~stub/pytz/devel
282
.. _Cheeseshop: http://cheeseshop.python.org/pypi/pytz/
283
.. _Sourceforge: http://sourceforge.net/projects/pytz/
421
This package will be updated after releases of the Olson timezone
422
database. The latest version can be downloaded from the Python Package
423
Index (PyPI_). The code that is used to generate this distribution is
424
hosted on launchpad.net and available using the Bazaar_ revision control
429
.. _PyPI: http://cheeseshop.python.org/pypi/pytz/
284
430
.. _Bazaar: http://bazaar-vcs.org/
286
432
Bugs, Feature Requests & Patches
added
removed
README.txt
