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
matplotlib-1.1.1.tar.gz （2000个子文件） 
Helvetica-Oblique.afm 73KB Helvetica.afm 73KB Helvetica-BoldOblique.afm 68KB Helvetica-Bold.afm 68KB Times-Italic.afm 65KB Times-Bold.afm 63KB Times-Roman.afm 59KB Times-BoldItalic.afm 58KB putr8a.afm 22KB putbi8a.afm 21KB putri8a.afm 21KB putb8a.afm 21KB ptmbi8a.afm 18KB ptmb8a.afm 18KB ptmr8a.afm 18KB phvro8a.afm 17KB phvro8an.afm 17KB phvr8a.afm 17KB pncbi8a.afm 17KB pagko8a.afm 17KB pagdo8a.afm 17KB pagk8a.afm 17KB phvbo8a.afm 17KB phvbo8an.afm 17KB phvb8an.afm 17KB pncr8a.afm 16KB pzcmi8a.afm 16KB pncb8a.afm 16KB pplbi8a.afm 15KB pplr8a.afm 15KB pplri8a.afm 15KB phvlo8a.afm 15KB phvl8a.afm 15KB pcrro8a.afm 15KB Courier-Oblique.afm 15KB pcrbo8a.afm 15KB Courier-BoldOblique.afm 15KB pcrb8a.afm 15KB pcrr8a.afm 15KB Courier.afm 15KB Courier-Bold.afm 15KB pbkdi8a.afm 15KB pbkli8a.afm 15KB pbkd8a.afm 15KB pbkl8a.afm 15KB cmex10.afm 12KB cmmi10.afm 10KB cmr10.afm 10KB Symbol.afm 10KB psyr.afm 9KB ZapfDingbats.afm 9KB cmsy10.afm 8KB cmtt10.afm 6KB cntr.c 63KB nxutils.c 7KB cxxextensions.c 2KB cxxextensions.c 2KB cxxextensions.c 2KB _backend_gdk.c 2KB backend_gdk.c 2KB matplotlib.conf 14KB local.conf 1012B agg_embedded_raster_fonts.cpp 385KB ft2font.cpp 73KB backend_agg.cpp 70KB _backend_agg.cpp 70KB image.cpp 55KB _image.cpp 55KB agg_platform_support.cpp 48KB _path.cpp 47KB path.cpp 47KB agg_platform_support.cpp 46KB pprdrv_tt.cpp 45KB _tri.cpp 36KB agg_platform_support.cpp 34KB VoronoiDiagramGenerator.cpp 34KB agg_gsv_text.cpp 32KB agg_platform_support.cpp 29KB pprdrv_tt2.cpp 26KB _delaunay.cpp 24KB agg_platform_support.cpp 24KB agg_platform_support.cpp 22KB agg_curves.cpp 19KB agg_win32_bmp.cpp 19KB _png.cpp 14KB agg_gamma_ctrl.cpp 13KB agg_scale_ctrl.cpp 13KB agg_spline_ctrl.cpp 11KB agg_bezier_ctrl.cpp 11KB agg_polygon_ctrl.cpp 10KB agg_slider_ctrl.cpp 10KB natneighbors.cpp 10KB agg_rbox_ctrl.cpp 9KB agg_mac_pmap.cpp 8KB agg_bezier_arc.cpp 8KB agg_sqrt_tables.cpp 8KB agg_trans_double_path.cpp 8KB agg_bspline.cpp 8KB _ttconv.cpp 7KB agg_vcgen_dash.cpp 7KB共 2000 条
- 1
- 2
- 3
- 4
- 5
- 6
- 20
资源评论
