jpayne@69: Metadata-Version: 2.1 jpayne@69: Name: pytz jpayne@69: Version: 2025.1 jpayne@69: Summary: World timezone definitions, modern and historical jpayne@69: Home-page: http://pythonhosted.org/pytz jpayne@69: Download-URL: https://pypi.org/project/pytz/ jpayne@69: Author: Stuart Bishop jpayne@69: Author-email: stuart@stuartbishop.net jpayne@69: Maintainer: Stuart Bishop jpayne@69: Maintainer-email: stuart@stuartbishop.net jpayne@69: License: MIT jpayne@69: Keywords: timezone,tzinfo,datetime,olson,time jpayne@69: Platform: Independent jpayne@69: Classifier: Development Status :: 6 - Mature jpayne@69: Classifier: Intended Audience :: Developers jpayne@69: Classifier: License :: OSI Approved :: MIT License jpayne@69: Classifier: Natural Language :: English jpayne@69: Classifier: Operating System :: OS Independent jpayne@69: Classifier: Programming Language :: Python jpayne@69: Classifier: Programming Language :: Python :: 2 jpayne@69: Classifier: Programming Language :: Python :: 2.4 jpayne@69: Classifier: Programming Language :: Python :: 2.5 jpayne@69: Classifier: Programming Language :: Python :: 2.6 jpayne@69: Classifier: Programming Language :: Python :: 2.7 jpayne@69: Classifier: Programming Language :: Python :: 3 jpayne@69: Classifier: Programming Language :: Python :: 3.1 jpayne@69: Classifier: Programming Language :: Python :: 3.2 jpayne@69: Classifier: Programming Language :: Python :: 3.3 jpayne@69: Classifier: Programming Language :: Python :: 3.4 jpayne@69: Classifier: Programming Language :: Python :: 3.5 jpayne@69: Classifier: Programming Language :: Python :: 3.6 jpayne@69: Classifier: Programming Language :: Python :: 3.7 jpayne@69: Classifier: Programming Language :: Python :: 3.8 jpayne@69: Classifier: Programming Language :: Python :: 3.9 jpayne@69: Classifier: Programming Language :: Python :: 3.10 jpayne@69: Classifier: Programming Language :: Python :: 3.11 jpayne@69: Classifier: Programming Language :: Python :: 3.12 jpayne@69: Classifier: Programming Language :: Python :: 3.13 jpayne@69: Classifier: Topic :: Software Development :: Libraries :: Python Modules jpayne@69: License-File: LICENSE.txt jpayne@69: jpayne@69: pytz - World Timezone Definitions for Python jpayne@69: ============================================ jpayne@69: jpayne@69: :Author: Stuart Bishop jpayne@69: jpayne@69: Introduction jpayne@69: ~~~~~~~~~~~~ jpayne@69: jpayne@69: pytz brings the Olson tz database into Python. This library allows jpayne@69: accurate and cross platform timezone calculations using Python 2.4 jpayne@69: or higher. It also solves the issue of ambiguous times at the end jpayne@69: of daylight saving time, which you can read more about in the Python jpayne@69: Library Reference (``datetime.tzinfo``). jpayne@69: jpayne@69: Almost all of the Olson timezones are supported. jpayne@69: jpayne@69: .. note:: jpayne@69: jpayne@69: Projects using Python 3.9 or later should be using the support jpayne@69: now included as part of the standard library, and third party jpayne@69: packages work with it such as `tzdata `_. jpayne@69: pytz offers no advantages beyond backwards compatibility with jpayne@69: code written for earlier versions of Python. jpayne@69: jpayne@69: .. note:: jpayne@69: jpayne@69: This library differs from the documented Python API for jpayne@69: tzinfo implementations; if you want to create local wallclock jpayne@69: times you need to use the ``localize()`` method documented in this jpayne@69: document. In addition, if you perform date arithmetic on local jpayne@69: times that cross DST boundaries, the result may be in an incorrect jpayne@69: timezone (ie. subtract 1 minute from 2002-10-27 1:00 EST and you get jpayne@69: 2002-10-27 0:59 EST instead of the correct 2002-10-27 1:59 EDT). A jpayne@69: ``normalize()`` method is provided to correct this. Unfortunately these jpayne@69: issues cannot be resolved without modifying the Python datetime jpayne@69: implementation (see PEP-431). jpayne@69: jpayne@69: jpayne@69: Installation jpayne@69: ~~~~~~~~~~~~ jpayne@69: jpayne@69: This package can either be installed using ``pip`` or from a tarball using the jpayne@69: standard Python distutils. jpayne@69: jpayne@69: If you are installing using ``pip``, you don't need to download anything as the jpayne@69: latest version will be downloaded for you from PyPI:: jpayne@69: jpayne@69: pip install pytz jpayne@69: jpayne@69: If you are installing from a tarball, run the following command as an jpayne@69: administrative user:: jpayne@69: jpayne@69: python setup.py install jpayne@69: jpayne@69: jpayne@69: pytz for Enterprise jpayne@69: ~~~~~~~~~~~~~~~~~~~ jpayne@69: jpayne@69: Available as part of the Tidelift Subscription. jpayne@69: jpayne@69: The maintainers of pytz and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. `Learn more. `_. jpayne@69: jpayne@69: jpayne@69: Example & Usage jpayne@69: ~~~~~~~~~~~~~~~ jpayne@69: jpayne@69: Localized times and date arithmetic jpayne@69: ----------------------------------- jpayne@69: jpayne@69: >>> from datetime import datetime, timedelta jpayne@69: >>> from pytz import timezone jpayne@69: >>> import pytz jpayne@69: >>> utc = pytz.utc jpayne@69: >>> utc.zone jpayne@69: 'UTC' jpayne@69: >>> eastern = timezone('US/Eastern') jpayne@69: >>> eastern.zone jpayne@69: 'US/Eastern' jpayne@69: >>> amsterdam = timezone('Europe/Amsterdam') jpayne@69: >>> fmt = '%Y-%m-%d %H:%M:%S %Z%z' jpayne@69: jpayne@69: This library only supports two ways of building a localized time. The jpayne@69: first is to use the ``localize()`` method provided by the pytz library. jpayne@69: This is used to localize a naive datetime (datetime with no timezone jpayne@69: information): jpayne@69: jpayne@69: >>> loc_dt = eastern.localize(datetime(2002, 10, 27, 6, 0, 0)) jpayne@69: >>> print(loc_dt.strftime(fmt)) jpayne@69: 2002-10-27 06:00:00 EST-0500 jpayne@69: jpayne@69: The second way of building a localized time is by converting an existing jpayne@69: localized time using the standard ``astimezone()`` method: jpayne@69: jpayne@69: >>> ams_dt = loc_dt.astimezone(amsterdam) jpayne@69: >>> ams_dt.strftime(fmt) jpayne@69: '2002-10-27 12:00:00 CET+0100' jpayne@69: jpayne@69: Unfortunately using the tzinfo argument of the standard datetime jpayne@69: constructors ''does not work'' with pytz for many timezones. jpayne@69: jpayne@69: >>> datetime(2002, 10, 27, 12, 0, 0, tzinfo=amsterdam).strftime(fmt) # /!\ Does not work this way! jpayne@69: '2002-10-27 12:00:00 LMT+0018' jpayne@69: jpayne@69: It is safe for timezones without daylight saving transitions though, such jpayne@69: as UTC: jpayne@69: jpayne@69: >>> datetime(2002, 10, 27, 12, 0, 0, tzinfo=pytz.utc).strftime(fmt) # /!\ Not recommended except for UTC jpayne@69: '2002-10-27 12:00:00 UTC+0000' jpayne@69: jpayne@69: The preferred way of dealing with times is to always work in UTC, jpayne@69: converting to localtime only when generating output to be read jpayne@69: by humans. jpayne@69: jpayne@69: >>> utc_dt = datetime(2002, 10, 27, 6, 0, 0, tzinfo=utc) jpayne@69: >>> loc_dt = utc_dt.astimezone(eastern) jpayne@69: >>> loc_dt.strftime(fmt) jpayne@69: '2002-10-27 01:00:00 EST-0500' jpayne@69: jpayne@69: This library also allows you to do date arithmetic using local jpayne@69: times, although it is more complicated than working in UTC as you jpayne@69: need to use the ``normalize()`` method to handle daylight saving time jpayne@69: and other timezone transitions. In this example, ``loc_dt`` is set jpayne@69: to the instant when daylight saving time ends in the US/Eastern jpayne@69: timezone. jpayne@69: jpayne@69: >>> before = loc_dt - timedelta(minutes=10) jpayne@69: >>> before.strftime(fmt) jpayne@69: '2002-10-27 00:50:00 EST-0500' jpayne@69: >>> eastern.normalize(before).strftime(fmt) jpayne@69: '2002-10-27 01:50:00 EDT-0400' jpayne@69: >>> after = eastern.normalize(before + timedelta(minutes=20)) jpayne@69: >>> after.strftime(fmt) jpayne@69: '2002-10-27 01:10:00 EST-0500' jpayne@69: jpayne@69: Creating local times is also tricky, and the reason why working with jpayne@69: local times is not recommended. Unfortunately, you cannot just pass jpayne@69: a ``tzinfo`` argument when constructing a datetime (see the next jpayne@69: section for more details) jpayne@69: jpayne@69: >>> dt = datetime(2002, 10, 27, 1, 30, 0) jpayne@69: >>> dt1 = eastern.localize(dt, is_dst=True) jpayne@69: >>> dt1.strftime(fmt) jpayne@69: '2002-10-27 01:30:00 EDT-0400' jpayne@69: >>> dt2 = eastern.localize(dt, is_dst=False) jpayne@69: >>> dt2.strftime(fmt) jpayne@69: '2002-10-27 01:30:00 EST-0500' jpayne@69: jpayne@69: Converting between timezones is more easily done, using the jpayne@69: standard astimezone method. jpayne@69: jpayne@69: >>> utc_dt = datetime.fromtimestamp(1143408899, tz=utc) jpayne@69: >>> utc_dt.strftime(fmt) jpayne@69: '2006-03-26 21:34:59 UTC+0000' jpayne@69: >>> au_tz = timezone('Australia/Sydney') jpayne@69: >>> au_dt = utc_dt.astimezone(au_tz) jpayne@69: >>> au_dt.strftime(fmt) jpayne@69: '2006-03-27 08:34:59 AEDT+1100' jpayne@69: >>> utc_dt2 = au_dt.astimezone(utc) jpayne@69: >>> utc_dt2.strftime(fmt) jpayne@69: '2006-03-26 21:34:59 UTC+0000' jpayne@69: >>> utc_dt == utc_dt2 jpayne@69: True jpayne@69: jpayne@69: You can take shortcuts when dealing with the UTC side of timezone jpayne@69: conversions. ``normalize()`` and ``localize()`` are not really jpayne@69: necessary when there are no daylight saving time transitions to jpayne@69: deal with. jpayne@69: jpayne@69: >>> utc_dt = datetime.fromtimestamp(1143408899, tz=utc) jpayne@69: >>> utc_dt.strftime(fmt) jpayne@69: '2006-03-26 21:34:59 UTC+0000' jpayne@69: >>> au_tz = timezone('Australia/Sydney') jpayne@69: >>> au_dt = au_tz.normalize(utc_dt.astimezone(au_tz)) jpayne@69: >>> au_dt.strftime(fmt) jpayne@69: '2006-03-27 08:34:59 AEDT+1100' jpayne@69: >>> utc_dt2 = au_dt.astimezone(utc) jpayne@69: >>> utc_dt2.strftime(fmt) jpayne@69: '2006-03-26 21:34:59 UTC+0000' jpayne@69: jpayne@69: jpayne@69: ``tzinfo`` API jpayne@69: -------------- jpayne@69: jpayne@69: The ``tzinfo`` instances returned by the ``timezone()`` function have jpayne@69: been extended to cope with ambiguous times by adding an ``is_dst`` jpayne@69: parameter to the ``utcoffset()``, ``dst()`` && ``tzname()`` methods. jpayne@69: jpayne@69: >>> tz = timezone('America/St_Johns') jpayne@69: jpayne@69: >>> normal = datetime(2009, 9, 1) jpayne@69: >>> ambiguous = datetime(2009, 10, 31, 23, 30) jpayne@69: jpayne@69: The ``is_dst`` parameter is ignored for most timestamps. It is only used jpayne@69: during DST transition ambiguous periods to resolve that ambiguity. jpayne@69: jpayne@69: >>> print(tz.utcoffset(normal, is_dst=True)) jpayne@69: -1 day, 21:30:00 jpayne@69: >>> print(tz.dst(normal, is_dst=True)) jpayne@69: 1:00:00 jpayne@69: >>> tz.tzname(normal, is_dst=True) jpayne@69: 'NDT' jpayne@69: jpayne@69: >>> print(tz.utcoffset(ambiguous, is_dst=True)) jpayne@69: -1 day, 21:30:00 jpayne@69: >>> print(tz.dst(ambiguous, is_dst=True)) jpayne@69: 1:00:00 jpayne@69: >>> tz.tzname(ambiguous, is_dst=True) jpayne@69: 'NDT' jpayne@69: jpayne@69: >>> print(tz.utcoffset(normal, is_dst=False)) jpayne@69: -1 day, 21:30:00 jpayne@69: >>> tz.dst(normal, is_dst=False).seconds jpayne@69: 3600 jpayne@69: >>> tz.tzname(normal, is_dst=False) jpayne@69: 'NDT' jpayne@69: jpayne@69: >>> print(tz.utcoffset(ambiguous, is_dst=False)) jpayne@69: -1 day, 20:30:00 jpayne@69: >>> tz.dst(ambiguous, is_dst=False) jpayne@69: datetime.timedelta(0) jpayne@69: >>> tz.tzname(ambiguous, is_dst=False) jpayne@69: 'NST' jpayne@69: jpayne@69: If ``is_dst`` is not specified, ambiguous timestamps will raise jpayne@69: an ``pytz.exceptions.AmbiguousTimeError`` exception. jpayne@69: jpayne@69: >>> print(tz.utcoffset(normal)) jpayne@69: -1 day, 21:30:00 jpayne@69: >>> print(tz.dst(normal)) jpayne@69: 1:00:00 jpayne@69: >>> tz.tzname(normal) jpayne@69: 'NDT' jpayne@69: jpayne@69: >>> import pytz.exceptions jpayne@69: >>> try: jpayne@69: ... tz.utcoffset(ambiguous) jpayne@69: ... except pytz.exceptions.AmbiguousTimeError: jpayne@69: ... print('pytz.exceptions.AmbiguousTimeError: %s' % ambiguous) jpayne@69: pytz.exceptions.AmbiguousTimeError: 2009-10-31 23:30:00 jpayne@69: >>> try: jpayne@69: ... tz.dst(ambiguous) jpayne@69: ... except pytz.exceptions.AmbiguousTimeError: jpayne@69: ... print('pytz.exceptions.AmbiguousTimeError: %s' % ambiguous) jpayne@69: pytz.exceptions.AmbiguousTimeError: 2009-10-31 23:30:00 jpayne@69: >>> try: jpayne@69: ... tz.tzname(ambiguous) jpayne@69: ... except pytz.exceptions.AmbiguousTimeError: jpayne@69: ... print('pytz.exceptions.AmbiguousTimeError: %s' % ambiguous) jpayne@69: pytz.exceptions.AmbiguousTimeError: 2009-10-31 23:30:00 jpayne@69: jpayne@69: jpayne@69: Problems with Localtime jpayne@69: ~~~~~~~~~~~~~~~~~~~~~~~ jpayne@69: jpayne@69: The major problem we have to deal with is that certain datetimes jpayne@69: may occur twice in a year. For example, in the US/Eastern timezone jpayne@69: on the last Sunday morning in October, the following sequence jpayne@69: happens: jpayne@69: jpayne@69: - 01:00 EDT occurs jpayne@69: - 1 hour later, instead of 2:00am the clock is turned back 1 hour jpayne@69: and 01:00 happens again (this time 01:00 EST) jpayne@69: jpayne@69: In fact, every instant between 01:00 and 02:00 occurs twice. This means jpayne@69: that if you try and create a time in the 'US/Eastern' timezone jpayne@69: the standard datetime syntax, there is no way to specify if you meant jpayne@69: before of after the end-of-daylight-saving-time transition. Using the jpayne@69: pytz custom syntax, the best you can do is make an educated guess: jpayne@69: jpayne@69: >>> loc_dt = eastern.localize(datetime(2002, 10, 27, 1, 30, 00)) jpayne@69: >>> loc_dt.strftime(fmt) jpayne@69: '2002-10-27 01:30:00 EST-0500' jpayne@69: jpayne@69: As you can see, the system has chosen one for you and there is a 50% jpayne@69: chance of it being out by one hour. For some applications, this does jpayne@69: not matter. However, if you are trying to schedule meetings with people jpayne@69: in different timezones or analyze log files it is not acceptable. jpayne@69: jpayne@69: The best and simplest solution is to stick with using UTC. The pytz jpayne@69: package encourages using UTC for internal timezone representation by jpayne@69: including a special UTC implementation based on the standard Python jpayne@69: reference implementation in the Python documentation. jpayne@69: jpayne@69: The UTC timezone unpickles to be the same instance, and pickles to a jpayne@69: smaller size than other pytz tzinfo instances. The UTC implementation jpayne@69: can be obtained as pytz.utc, pytz.UTC, or pytz.timezone('UTC'). jpayne@69: jpayne@69: >>> import pickle, pytz jpayne@69: >>> dt = datetime(2005, 3, 1, 14, 13, 21, tzinfo=utc) jpayne@69: >>> naive = dt.replace(tzinfo=None) jpayne@69: >>> p = pickle.dumps(dt, 1) jpayne@69: >>> naive_p = pickle.dumps(naive, 1) jpayne@69: >>> len(p) - len(naive_p) jpayne@69: 17 jpayne@69: >>> new = pickle.loads(p) jpayne@69: >>> new == dt jpayne@69: True jpayne@69: >>> new is dt jpayne@69: False jpayne@69: >>> new.tzinfo is dt.tzinfo jpayne@69: True jpayne@69: >>> pytz.utc is pytz.UTC is pytz.timezone('UTC') jpayne@69: True jpayne@69: jpayne@69: Note that some other timezones are commonly thought of as the same (GMT, jpayne@69: Greenwich, Universal, etc.). The definition of UTC is distinct from these jpayne@69: other timezones, and they are not equivalent. For this reason, they will jpayne@69: not compare the same in Python. jpayne@69: jpayne@69: >>> utc == pytz.timezone('GMT') jpayne@69: False jpayne@69: jpayne@69: See the section `What is UTC`_, below. jpayne@69: jpayne@69: If you insist on working with local times, this library provides a jpayne@69: facility for constructing them unambiguously: jpayne@69: jpayne@69: >>> loc_dt = datetime(2002, 10, 27, 1, 30, 00) jpayne@69: >>> est_dt = eastern.localize(loc_dt, is_dst=True) jpayne@69: >>> edt_dt = eastern.localize(loc_dt, is_dst=False) jpayne@69: >>> print(est_dt.strftime(fmt) + ' / ' + edt_dt.strftime(fmt)) jpayne@69: 2002-10-27 01:30:00 EDT-0400 / 2002-10-27 01:30:00 EST-0500 jpayne@69: jpayne@69: If you pass None as the is_dst flag to localize(), pytz will refuse to jpayne@69: guess and raise exceptions if you try to build ambiguous or non-existent jpayne@69: times. jpayne@69: jpayne@69: For example, 1:30am on 27th Oct 2002 happened twice in the US/Eastern jpayne@69: timezone when the clocks where put back at the end of Daylight Saving jpayne@69: Time: jpayne@69: jpayne@69: >>> dt = datetime(2002, 10, 27, 1, 30, 00) jpayne@69: >>> try: jpayne@69: ... eastern.localize(dt, is_dst=None) jpayne@69: ... except pytz.exceptions.AmbiguousTimeError: jpayne@69: ... print('pytz.exceptions.AmbiguousTimeError: %s' % dt) jpayne@69: pytz.exceptions.AmbiguousTimeError: 2002-10-27 01:30:00 jpayne@69: jpayne@69: Similarly, 2:30am on 7th April 2002 never happened at all in the jpayne@69: US/Eastern timezone, as the clocks where put forward at 2:00am skipping jpayne@69: the entire hour: jpayne@69: jpayne@69: >>> dt = datetime(2002, 4, 7, 2, 30, 00) jpayne@69: >>> try: jpayne@69: ... eastern.localize(dt, is_dst=None) jpayne@69: ... except pytz.exceptions.NonExistentTimeError: jpayne@69: ... print('pytz.exceptions.NonExistentTimeError: %s' % dt) jpayne@69: pytz.exceptions.NonExistentTimeError: 2002-04-07 02:30:00 jpayne@69: jpayne@69: Both of these exceptions share a common base class to make error handling jpayne@69: easier: jpayne@69: jpayne@69: >>> isinstance(pytz.AmbiguousTimeError(), pytz.InvalidTimeError) jpayne@69: True jpayne@69: >>> isinstance(pytz.NonExistentTimeError(), pytz.InvalidTimeError) jpayne@69: True jpayne@69: jpayne@69: jpayne@69: A special case is where countries change their timezone definitions jpayne@69: with no daylight savings time switch. For example, in 1915 Warsaw jpayne@69: switched from Warsaw time to Central European time with no daylight savings jpayne@69: transition. So at the stroke of midnight on August 5th 1915 the clocks jpayne@69: were wound back 24 minutes creating an ambiguous time period that cannot jpayne@69: be specified without referring to the timezone abbreviation or the jpayne@69: actual UTC offset. In this case midnight happened twice, neither time jpayne@69: during a daylight saving time period. pytz handles this transition by jpayne@69: treating the ambiguous period before the switch as daylight savings jpayne@69: time, and the ambiguous period after as standard time. jpayne@69: jpayne@69: jpayne@69: >>> warsaw = pytz.timezone('Europe/Warsaw') jpayne@69: >>> amb_dt1 = warsaw.localize(datetime(1915, 8, 4, 23, 59, 59), is_dst=True) jpayne@69: >>> amb_dt1.strftime(fmt) jpayne@69: '1915-08-04 23:59:59 WMT+0124' jpayne@69: >>> amb_dt2 = warsaw.localize(datetime(1915, 8, 4, 23, 59, 59), is_dst=False) jpayne@69: >>> amb_dt2.strftime(fmt) jpayne@69: '1915-08-04 23:59:59 CET+0100' jpayne@69: >>> switch_dt = warsaw.localize(datetime(1915, 8, 5, 00, 00, 00), is_dst=False) jpayne@69: >>> switch_dt.strftime(fmt) jpayne@69: '1915-08-05 00:00:00 CET+0100' jpayne@69: >>> str(switch_dt - amb_dt1) jpayne@69: '0:24:01' jpayne@69: >>> str(switch_dt - amb_dt2) jpayne@69: '0:00:01' jpayne@69: jpayne@69: The best way of creating a time during an ambiguous time period is jpayne@69: by converting from another timezone such as UTC: jpayne@69: jpayne@69: >>> utc_dt = datetime(1915, 8, 4, 22, 36, tzinfo=pytz.utc) jpayne@69: >>> utc_dt.astimezone(warsaw).strftime(fmt) jpayne@69: '1915-08-04 23:36:00 CET+0100' jpayne@69: jpayne@69: The standard Python way of handling all these ambiguities is not to jpayne@69: handle them, such as demonstrated in this example using the US/Eastern jpayne@69: timezone definition from the Python documentation (Note that this jpayne@69: implementation only works for dates between 1987 and 2006 - it is jpayne@69: included for tests only!): jpayne@69: jpayne@69: >>> from pytz.reference import Eastern # pytz.reference only for tests jpayne@69: >>> dt = datetime(2002, 10, 27, 0, 30, tzinfo=Eastern) jpayne@69: >>> str(dt) jpayne@69: '2002-10-27 00:30:00-04:00' jpayne@69: >>> str(dt + timedelta(hours=1)) jpayne@69: '2002-10-27 01:30:00-05:00' jpayne@69: >>> str(dt + timedelta(hours=2)) jpayne@69: '2002-10-27 02:30:00-05:00' jpayne@69: >>> str(dt + timedelta(hours=3)) jpayne@69: '2002-10-27 03:30:00-05:00' jpayne@69: jpayne@69: Notice the first two results? At first glance you might think they are jpayne@69: correct, but taking the UTC offset into account you find that they are jpayne@69: actually two hours appart instead of the 1 hour we asked for. jpayne@69: jpayne@69: >>> from pytz.reference import UTC # pytz.reference only for tests jpayne@69: >>> str(dt.astimezone(UTC)) jpayne@69: '2002-10-27 04:30:00+00:00' jpayne@69: >>> str((dt + timedelta(hours=1)).astimezone(UTC)) jpayne@69: '2002-10-27 06:30:00+00:00' jpayne@69: jpayne@69: jpayne@69: Country Information jpayne@69: ~~~~~~~~~~~~~~~~~~~ jpayne@69: jpayne@69: A mechanism is provided to access the timezones commonly in use jpayne@69: for a particular country, looked up using the ISO 3166 country code. jpayne@69: It returns a list of strings that can be used to retrieve the relevant jpayne@69: tzinfo instance using ``pytz.timezone()``: jpayne@69: jpayne@69: >>> print(' '.join(pytz.country_timezones['nz'])) jpayne@69: Pacific/Auckland Pacific/Chatham jpayne@69: jpayne@69: The Olson database comes with a ISO 3166 country code to English country jpayne@69: name mapping that pytz exposes as a dictionary: jpayne@69: jpayne@69: >>> print(pytz.country_names['nz']) jpayne@69: New Zealand jpayne@69: jpayne@69: jpayne@69: What is UTC jpayne@69: ~~~~~~~~~~~ jpayne@69: jpayne@69: 'UTC' is `Coordinated Universal Time`_. It is a successor to, but distinct jpayne@69: from, Greenwich Mean Time (GMT) and the various definitions of Universal jpayne@69: Time. UTC is now the worldwide standard for regulating clocks and time jpayne@69: measurement. jpayne@69: jpayne@69: All other timezones are defined relative to UTC, and include offsets like jpayne@69: UTC+0800 - hours to add or subtract from UTC to derive the local time. No jpayne@69: daylight saving time occurs in UTC, making it a useful timezone to perform jpayne@69: date arithmetic without worrying about the confusion and ambiguities caused jpayne@69: by daylight saving time transitions, your country changing its timezone, or jpayne@69: mobile computers that roam through multiple timezones. jpayne@69: jpayne@69: .. _Coordinated Universal Time: https://en.wikipedia.org/wiki/Coordinated_Universal_Time jpayne@69: jpayne@69: jpayne@69: Helpers jpayne@69: ~~~~~~~ jpayne@69: jpayne@69: There are two lists of timezones provided. jpayne@69: jpayne@69: ``all_timezones`` is the exhaustive list of the timezone names that can jpayne@69: be used. jpayne@69: jpayne@69: >>> from pytz import all_timezones jpayne@69: >>> len(all_timezones) >= 500 jpayne@69: True jpayne@69: >>> 'Etc/Greenwich' in all_timezones jpayne@69: True jpayne@69: jpayne@69: ``common_timezones`` is a list of useful, current timezones. It doesn't jpayne@69: contain deprecated zones or historical zones, except for a few I've jpayne@69: deemed in common usage, such as US/Eastern (open a bug report if you jpayne@69: think other timezones are deserving of being included here). It is also jpayne@69: a sequence of strings. jpayne@69: jpayne@69: >>> from pytz import common_timezones jpayne@69: >>> len(common_timezones) < len(all_timezones) jpayne@69: True jpayne@69: >>> 'Etc/Greenwich' in common_timezones jpayne@69: False jpayne@69: >>> 'Australia/Melbourne' in common_timezones jpayne@69: True jpayne@69: >>> 'US/Eastern' in common_timezones jpayne@69: True jpayne@69: >>> 'Canada/Eastern' in common_timezones jpayne@69: True jpayne@69: >>> 'Australia/Yancowinna' in all_timezones jpayne@69: True jpayne@69: >>> 'Australia/Yancowinna' in common_timezones jpayne@69: False jpayne@69: jpayne@69: Both ``common_timezones`` and ``all_timezones`` are alphabetically jpayne@69: sorted: jpayne@69: jpayne@69: >>> common_timezones_dupe = common_timezones[:] jpayne@69: >>> common_timezones_dupe.sort() jpayne@69: >>> common_timezones == common_timezones_dupe jpayne@69: True jpayne@69: >>> all_timezones_dupe = all_timezones[:] jpayne@69: >>> all_timezones_dupe.sort() jpayne@69: >>> all_timezones == all_timezones_dupe jpayne@69: True jpayne@69: jpayne@69: ``all_timezones`` and ``common_timezones`` are also available as sets. jpayne@69: jpayne@69: >>> from pytz import all_timezones_set, common_timezones_set jpayne@69: >>> 'US/Eastern' in all_timezones_set jpayne@69: True jpayne@69: >>> 'US/Eastern' in common_timezones_set jpayne@69: True jpayne@69: >>> 'Australia/Victoria' in common_timezones_set jpayne@69: False jpayne@69: jpayne@69: You can also retrieve lists of timezones used by particular countries jpayne@69: using the ``country_timezones()`` function. It requires an ISO-3166 jpayne@69: two letter country code. jpayne@69: jpayne@69: >>> from pytz import country_timezones jpayne@69: >>> print(' '.join(country_timezones('ch'))) jpayne@69: Europe/Zurich jpayne@69: >>> print(' '.join(country_timezones('CH'))) jpayne@69: Europe/Zurich jpayne@69: jpayne@69: jpayne@69: Internationalization - i18n/l10n jpayne@69: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ jpayne@69: jpayne@69: Pytz is an interface to the IANA database, which uses ASCII names. The `Unicode Consortium's Unicode Locales (CLDR) `_ jpayne@69: project provides translations. Python packages such as jpayne@69: `Babel `_ jpayne@69: and Thomas Khyn's `l18n `_ package can be used jpayne@69: to access these translations from Python. jpayne@69: jpayne@69: jpayne@69: License jpayne@69: ~~~~~~~ jpayne@69: jpayne@69: MIT license. jpayne@69: jpayne@69: This code is also available as part of Zope 3 under the Zope Public jpayne@69: License, Version 2.1 (ZPL). jpayne@69: jpayne@69: I'm happy to relicense this code if necessary for inclusion in other jpayne@69: open source projects. jpayne@69: jpayne@69: jpayne@69: Latest Versions jpayne@69: ~~~~~~~~~~~~~~~ jpayne@69: jpayne@69: This package will be updated after releases of the Olson timezone jpayne@69: database. The latest version can be downloaded from the `Python Package jpayne@69: Index `_. The code that is used jpayne@69: to generate this distribution is hosted on Github and available jpayne@69: using git:: jpayne@69: jpayne@69: git clone https://github.com/stub42/pytz.git jpayne@69: jpayne@69: Announcements of new releases are made on jpayne@69: `Launchpad `_, and the jpayne@69: `Atom feed `_ jpayne@69: hosted there. jpayne@69: jpayne@69: jpayne@69: Bugs, Feature Requests & Patches jpayne@69: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ jpayne@69: jpayne@69: Bugs should be reported on `Github `_. jpayne@69: Feature requests are unlikely to be considered, and efforts instead directed jpayne@69: to timezone support now built into Python or packages that work with it. jpayne@69: jpayne@69: jpayne@69: Security Issues jpayne@69: ~~~~~~~~~~~~~~~ jpayne@69: jpayne@69: Reports about security issues can be made via `Tidelift `_. jpayne@69: jpayne@69: jpayne@69: Issues & Limitations jpayne@69: ~~~~~~~~~~~~~~~~~~~~ jpayne@69: jpayne@69: - This project is in maintenance mode. Projects using Python 3.9 or later jpayne@69: are best served by using the timezone functionaly now included in core jpayne@69: Python and packages that work with it such as `tzdata `_. jpayne@69: jpayne@69: - Offsets from UTC are rounded to the nearest whole minute, so timezones jpayne@69: such as Europe/Amsterdam pre 1937 will be up to 30 seconds out. This jpayne@69: was a limitation of the Python datetime library. jpayne@69: jpayne@69: - If you think a timezone definition is incorrect, I probably can't fix jpayne@69: it. pytz is a direct translation of the Olson timezone database, and jpayne@69: changes to the timezone definitions need to be made to this source. jpayne@69: If you find errors they should be reported to the time zone mailing jpayne@69: list, linked from http://www.iana.org/time-zones. jpayne@69: jpayne@69: jpayne@69: Further Reading jpayne@69: ~~~~~~~~~~~~~~~ jpayne@69: jpayne@69: More info than you want to know about timezones: jpayne@69: https://data.iana.org/time-zones/tz-link.html jpayne@69: jpayne@69: jpayne@69: Contact jpayne@69: ~~~~~~~ jpayne@69: jpayne@69: Stuart Bishop