Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/lib/python3.8/site-packages/pytz-2025.1.dist-info/METADATA @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 Metadata-Version: 2.1
jpayne@69 2 Name: pytz
jpayne@69 3 Version: 2025.1
jpayne@69 4 Summary: World timezone definitions, modern and historical
jpayne@69 5 Home-page: http://pythonhosted.org/pytz
jpayne@69 6 Download-URL: https://pypi.org/project/pytz/
jpayne@69 7 Author: Stuart Bishop
jpayne@69 8 Author-email: stuart@stuartbishop.net
jpayne@69 9 Maintainer: Stuart Bishop
jpayne@69 10 Maintainer-email: stuart@stuartbishop.net
jpayne@69 11 License: MIT
jpayne@69 12 Keywords: timezone,tzinfo,datetime,olson,time
jpayne@69 13 Platform: Independent
jpayne@69 14 Classifier: Development Status :: 6 - Mature
jpayne@69 15 Classifier: Intended Audience :: Developers
jpayne@69 16 Classifier: License :: OSI Approved :: MIT License
jpayne@69 17 Classifier: Natural Language :: English
jpayne@69 18 Classifier: Operating System :: OS Independent
jpayne@69 19 Classifier: Programming Language :: Python
jpayne@69 20 Classifier: Programming Language :: Python :: 2
jpayne@69 21 Classifier: Programming Language :: Python :: 2.4
jpayne@69 22 Classifier: Programming Language :: Python :: 2.5
jpayne@69 23 Classifier: Programming Language :: Python :: 2.6
jpayne@69 24 Classifier: Programming Language :: Python :: 2.7
jpayne@69 25 Classifier: Programming Language :: Python :: 3
jpayne@69 26 Classifier: Programming Language :: Python :: 3.1
jpayne@69 27 Classifier: Programming Language :: Python :: 3.2
jpayne@69 28 Classifier: Programming Language :: Python :: 3.3
jpayne@69 29 Classifier: Programming Language :: Python :: 3.4
jpayne@69 30 Classifier: Programming Language :: Python :: 3.5
jpayne@69 31 Classifier: Programming Language :: Python :: 3.6
jpayne@69 32 Classifier: Programming Language :: Python :: 3.7
jpayne@69 33 Classifier: Programming Language :: Python :: 3.8
jpayne@69 34 Classifier: Programming Language :: Python :: 3.9
jpayne@69 35 Classifier: Programming Language :: Python :: 3.10
jpayne@69 36 Classifier: Programming Language :: Python :: 3.11
jpayne@69 37 Classifier: Programming Language :: Python :: 3.12
jpayne@69 38 Classifier: Programming Language :: Python :: 3.13
jpayne@69 39 Classifier: Topic :: Software Development :: Libraries :: Python Modules
jpayne@69 40 License-File: LICENSE.txt
jpayne@69 41
jpayne@69 42 pytz - World Timezone Definitions for Python
jpayne@69 43 ============================================
jpayne@69 44
jpayne@69 45 :Author: Stuart Bishop <stuart@stuartbishop.net>
jpayne@69 46
jpayne@69 47 Introduction
jpayne@69 48 ~~~~~~~~~~~~
jpayne@69 49
jpayne@69 50 pytz brings the Olson tz database into Python. This library allows
jpayne@69 51 accurate and cross platform timezone calculations using Python 2.4
jpayne@69 52 or higher. It also solves the issue of ambiguous times at the end
jpayne@69 53 of daylight saving time, which you can read more about in the Python
jpayne@69 54 Library Reference (``datetime.tzinfo``).
jpayne@69 55
jpayne@69 56 Almost all of the Olson timezones are supported.
jpayne@69 57
jpayne@69 58 .. note::
jpayne@69 59
jpayne@69 60 Projects using Python 3.9 or later should be using the support
jpayne@69 61 now included as part of the standard library, and third party
jpayne@69 62 packages work with it such as `tzdata <https://pypi.org/project/tzdata/>`_.
jpayne@69 63 pytz offers no advantages beyond backwards compatibility with
jpayne@69 64 code written for earlier versions of Python.
jpayne@69 65
jpayne@69 66 .. note::
jpayne@69 67
jpayne@69 68 This library differs from the documented Python API for
jpayne@69 69 tzinfo implementations; if you want to create local wallclock
jpayne@69 70 times you need to use the ``localize()`` method documented in this
jpayne@69 71 document. In addition, if you perform date arithmetic on local
jpayne@69 72 times that cross DST boundaries, the result may be in an incorrect
jpayne@69 73 timezone (ie. subtract 1 minute from 2002-10-27 1:00 EST and you get
jpayne@69 74 2002-10-27 0:59 EST instead of the correct 2002-10-27 1:59 EDT). A
jpayne@69 75 ``normalize()`` method is provided to correct this. Unfortunately these
jpayne@69 76 issues cannot be resolved without modifying the Python datetime
jpayne@69 77 implementation (see PEP-431).
jpayne@69 78
jpayne@69 79
jpayne@69 80 Installation
jpayne@69 81 ~~~~~~~~~~~~
jpayne@69 82
jpayne@69 83 This package can either be installed using ``pip`` or from a tarball using the
jpayne@69 84 standard Python distutils.
jpayne@69 85
jpayne@69 86 If you are installing using ``pip``, you don't need to download anything as the
jpayne@69 87 latest version will be downloaded for you from PyPI::
jpayne@69 88
jpayne@69 89 pip install pytz
jpayne@69 90
jpayne@69 91 If you are installing from a tarball, run the following command as an
jpayne@69 92 administrative user::
jpayne@69 93
jpayne@69 94 python setup.py install
jpayne@69 95
jpayne@69 96
jpayne@69 97 pytz for Enterprise
jpayne@69 98 ~~~~~~~~~~~~~~~~~~~
jpayne@69 99
jpayne@69 100 Available as part of the Tidelift Subscription.
jpayne@69 101
jpayne@69 102 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. <https://tidelift.com/subscription/pkg/pypi-pytz?utm_source=pypi-pytz&utm_medium=referral&utm_campaign=enterprise&utm_term=repo>`_.
jpayne@69 103
jpayne@69 104
jpayne@69 105 Example & Usage
jpayne@69 106 ~~~~~~~~~~~~~~~
jpayne@69 107
jpayne@69 108 Localized times and date arithmetic
jpayne@69 109 -----------------------------------
jpayne@69 110
jpayne@69 111 >>> from datetime import datetime, timedelta
jpayne@69 112 >>> from pytz import timezone
jpayne@69 113 >>> import pytz
jpayne@69 114 >>> utc = pytz.utc
jpayne@69 115 >>> utc.zone
jpayne@69 116 'UTC'
jpayne@69 117 >>> eastern = timezone('US/Eastern')
jpayne@69 118 >>> eastern.zone
jpayne@69 119 'US/Eastern'
jpayne@69 120 >>> amsterdam = timezone('Europe/Amsterdam')
jpayne@69 121 >>> fmt = '%Y-%m-%d %H:%M:%S %Z%z'
jpayne@69 122
jpayne@69 123 This library only supports two ways of building a localized time. The
jpayne@69 124 first is to use the ``localize()`` method provided by the pytz library.
jpayne@69 125 This is used to localize a naive datetime (datetime with no timezone
jpayne@69 126 information):
jpayne@69 127
jpayne@69 128 >>> loc_dt = eastern.localize(datetime(2002, 10, 27, 6, 0, 0))
jpayne@69 129 >>> print(loc_dt.strftime(fmt))
jpayne@69 130 2002-10-27 06:00:00 EST-0500
jpayne@69 131
jpayne@69 132 The second way of building a localized time is by converting an existing
jpayne@69 133 localized time using the standard ``astimezone()`` method:
jpayne@69 134
jpayne@69 135 >>> ams_dt = loc_dt.astimezone(amsterdam)
jpayne@69 136 >>> ams_dt.strftime(fmt)
jpayne@69 137 '2002-10-27 12:00:00 CET+0100'
jpayne@69 138
jpayne@69 139 Unfortunately using the tzinfo argument of the standard datetime
jpayne@69 140 constructors ''does not work'' with pytz for many timezones.
jpayne@69 141
jpayne@69 142 >>> datetime(2002, 10, 27, 12, 0, 0, tzinfo=amsterdam).strftime(fmt) # /!\ Does not work this way!
jpayne@69 143 '2002-10-27 12:00:00 LMT+0018'
jpayne@69 144
jpayne@69 145 It is safe for timezones without daylight saving transitions though, such
jpayne@69 146 as UTC:
jpayne@69 147
jpayne@69 148 >>> datetime(2002, 10, 27, 12, 0, 0, tzinfo=pytz.utc).strftime(fmt) # /!\ Not recommended except for UTC
jpayne@69 149 '2002-10-27 12:00:00 UTC+0000'
jpayne@69 150
jpayne@69 151 The preferred way of dealing with times is to always work in UTC,
jpayne@69 152 converting to localtime only when generating output to be read
jpayne@69 153 by humans.
jpayne@69 154
jpayne@69 155 >>> utc_dt = datetime(2002, 10, 27, 6, 0, 0, tzinfo=utc)
jpayne@69 156 >>> loc_dt = utc_dt.astimezone(eastern)
jpayne@69 157 >>> loc_dt.strftime(fmt)
jpayne@69 158 '2002-10-27 01:00:00 EST-0500'
jpayne@69 159
jpayne@69 160 This library also allows you to do date arithmetic using local
jpayne@69 161 times, although it is more complicated than working in UTC as you
jpayne@69 162 need to use the ``normalize()`` method to handle daylight saving time
jpayne@69 163 and other timezone transitions. In this example, ``loc_dt`` is set
jpayne@69 164 to the instant when daylight saving time ends in the US/Eastern
jpayne@69 165 timezone.
jpayne@69 166
jpayne@69 167 >>> before = loc_dt - timedelta(minutes=10)
jpayne@69 168 >>> before.strftime(fmt)
jpayne@69 169 '2002-10-27 00:50:00 EST-0500'
jpayne@69 170 >>> eastern.normalize(before).strftime(fmt)
jpayne@69 171 '2002-10-27 01:50:00 EDT-0400'
jpayne@69 172 >>> after = eastern.normalize(before + timedelta(minutes=20))
jpayne@69 173 >>> after.strftime(fmt)
jpayne@69 174 '2002-10-27 01:10:00 EST-0500'
jpayne@69 175
jpayne@69 176 Creating local times is also tricky, and the reason why working with
jpayne@69 177 local times is not recommended. Unfortunately, you cannot just pass
jpayne@69 178 a ``tzinfo`` argument when constructing a datetime (see the next
jpayne@69 179 section for more details)
jpayne@69 180
jpayne@69 181 >>> dt = datetime(2002, 10, 27, 1, 30, 0)
jpayne@69 182 >>> dt1 = eastern.localize(dt, is_dst=True)
jpayne@69 183 >>> dt1.strftime(fmt)
jpayne@69 184 '2002-10-27 01:30:00 EDT-0400'
jpayne@69 185 >>> dt2 = eastern.localize(dt, is_dst=False)
jpayne@69 186 >>> dt2.strftime(fmt)
jpayne@69 187 '2002-10-27 01:30:00 EST-0500'
jpayne@69 188
jpayne@69 189 Converting between timezones is more easily done, using the
jpayne@69 190 standard astimezone method.
jpayne@69 191
jpayne@69 192 >>> utc_dt = datetime.fromtimestamp(1143408899, tz=utc)
jpayne@69 193 >>> utc_dt.strftime(fmt)
jpayne@69 194 '2006-03-26 21:34:59 UTC+0000'
jpayne@69 195 >>> au_tz = timezone('Australia/Sydney')
jpayne@69 196 >>> au_dt = utc_dt.astimezone(au_tz)
jpayne@69 197 >>> au_dt.strftime(fmt)
jpayne@69 198 '2006-03-27 08:34:59 AEDT+1100'
jpayne@69 199 >>> utc_dt2 = au_dt.astimezone(utc)
jpayne@69 200 >>> utc_dt2.strftime(fmt)
jpayne@69 201 '2006-03-26 21:34:59 UTC+0000'
jpayne@69 202 >>> utc_dt == utc_dt2
jpayne@69 203 True
jpayne@69 204
jpayne@69 205 You can take shortcuts when dealing with the UTC side of timezone
jpayne@69 206 conversions. ``normalize()`` and ``localize()`` are not really
jpayne@69 207 necessary when there are no daylight saving time transitions to
jpayne@69 208 deal with.
jpayne@69 209
jpayne@69 210 >>> utc_dt = datetime.fromtimestamp(1143408899, tz=utc)
jpayne@69 211 >>> utc_dt.strftime(fmt)
jpayne@69 212 '2006-03-26 21:34:59 UTC+0000'
jpayne@69 213 >>> au_tz = timezone('Australia/Sydney')
jpayne@69 214 >>> au_dt = au_tz.normalize(utc_dt.astimezone(au_tz))
jpayne@69 215 >>> au_dt.strftime(fmt)
jpayne@69 216 '2006-03-27 08:34:59 AEDT+1100'
jpayne@69 217 >>> utc_dt2 = au_dt.astimezone(utc)
jpayne@69 218 >>> utc_dt2.strftime(fmt)
jpayne@69 219 '2006-03-26 21:34:59 UTC+0000'
jpayne@69 220
jpayne@69 221
jpayne@69 222 ``tzinfo`` API
jpayne@69 223 --------------
jpayne@69 224
jpayne@69 225 The ``tzinfo`` instances returned by the ``timezone()`` function have
jpayne@69 226 been extended to cope with ambiguous times by adding an ``is_dst``
jpayne@69 227 parameter to the ``utcoffset()``, ``dst()`` && ``tzname()`` methods.
jpayne@69 228
jpayne@69 229 >>> tz = timezone('America/St_Johns')
jpayne@69 230
jpayne@69 231 >>> normal = datetime(2009, 9, 1)
jpayne@69 232 >>> ambiguous = datetime(2009, 10, 31, 23, 30)
jpayne@69 233
jpayne@69 234 The ``is_dst`` parameter is ignored for most timestamps. It is only used
jpayne@69 235 during DST transition ambiguous periods to resolve that ambiguity.
jpayne@69 236
jpayne@69 237 >>> print(tz.utcoffset(normal, is_dst=True))
jpayne@69 238 -1 day, 21:30:00
jpayne@69 239 >>> print(tz.dst(normal, is_dst=True))
jpayne@69 240 1:00:00
jpayne@69 241 >>> tz.tzname(normal, is_dst=True)
jpayne@69 242 'NDT'
jpayne@69 243
jpayne@69 244 >>> print(tz.utcoffset(ambiguous, is_dst=True))
jpayne@69 245 -1 day, 21:30:00
jpayne@69 246 >>> print(tz.dst(ambiguous, is_dst=True))
jpayne@69 247 1:00:00
jpayne@69 248 >>> tz.tzname(ambiguous, is_dst=True)
jpayne@69 249 'NDT'
jpayne@69 250
jpayne@69 251 >>> print(tz.utcoffset(normal, is_dst=False))
jpayne@69 252 -1 day, 21:30:00
jpayne@69 253 >>> tz.dst(normal, is_dst=False).seconds
jpayne@69 254 3600
jpayne@69 255 >>> tz.tzname(normal, is_dst=False)
jpayne@69 256 'NDT'
jpayne@69 257
jpayne@69 258 >>> print(tz.utcoffset(ambiguous, is_dst=False))
jpayne@69 259 -1 day, 20:30:00
jpayne@69 260 >>> tz.dst(ambiguous, is_dst=False)
jpayne@69 261 datetime.timedelta(0)
jpayne@69 262 >>> tz.tzname(ambiguous, is_dst=False)
jpayne@69 263 'NST'
jpayne@69 264
jpayne@69 265 If ``is_dst`` is not specified, ambiguous timestamps will raise
jpayne@69 266 an ``pytz.exceptions.AmbiguousTimeError`` exception.
jpayne@69 267
jpayne@69 268 >>> print(tz.utcoffset(normal))
jpayne@69 269 -1 day, 21:30:00
jpayne@69 270 >>> print(tz.dst(normal))
jpayne@69 271 1:00:00
jpayne@69 272 >>> tz.tzname(normal)
jpayne@69 273 'NDT'
jpayne@69 274
jpayne@69 275 >>> import pytz.exceptions
jpayne@69 276 >>> try:
jpayne@69 277 ... tz.utcoffset(ambiguous)
jpayne@69 278 ... except pytz.exceptions.AmbiguousTimeError:
jpayne@69 279 ... print('pytz.exceptions.AmbiguousTimeError: %s' % ambiguous)
jpayne@69 280 pytz.exceptions.AmbiguousTimeError: 2009-10-31 23:30:00
jpayne@69 281 >>> try:
jpayne@69 282 ... tz.dst(ambiguous)
jpayne@69 283 ... except pytz.exceptions.AmbiguousTimeError:
jpayne@69 284 ... print('pytz.exceptions.AmbiguousTimeError: %s' % ambiguous)
jpayne@69 285 pytz.exceptions.AmbiguousTimeError: 2009-10-31 23:30:00
jpayne@69 286 >>> try:
jpayne@69 287 ... tz.tzname(ambiguous)
jpayne@69 288 ... except pytz.exceptions.AmbiguousTimeError:
jpayne@69 289 ... print('pytz.exceptions.AmbiguousTimeError: %s' % ambiguous)
jpayne@69 290 pytz.exceptions.AmbiguousTimeError: 2009-10-31 23:30:00
jpayne@69 291
jpayne@69 292
jpayne@69 293 Problems with Localtime
jpayne@69 294 ~~~~~~~~~~~~~~~~~~~~~~~
jpayne@69 295
jpayne@69 296 The major problem we have to deal with is that certain datetimes
jpayne@69 297 may occur twice in a year. For example, in the US/Eastern timezone
jpayne@69 298 on the last Sunday morning in October, the following sequence
jpayne@69 299 happens:
jpayne@69 300
jpayne@69 301 - 01:00 EDT occurs
jpayne@69 302 - 1 hour later, instead of 2:00am the clock is turned back 1 hour
jpayne@69 303 and 01:00 happens again (this time 01:00 EST)
jpayne@69 304
jpayne@69 305 In fact, every instant between 01:00 and 02:00 occurs twice. This means
jpayne@69 306 that if you try and create a time in the 'US/Eastern' timezone
jpayne@69 307 the standard datetime syntax, there is no way to specify if you meant
jpayne@69 308 before of after the end-of-daylight-saving-time transition. Using the
jpayne@69 309 pytz custom syntax, the best you can do is make an educated guess:
jpayne@69 310
jpayne@69 311 >>> loc_dt = eastern.localize(datetime(2002, 10, 27, 1, 30, 00))
jpayne@69 312 >>> loc_dt.strftime(fmt)
jpayne@69 313 '2002-10-27 01:30:00 EST-0500'
jpayne@69 314
jpayne@69 315 As you can see, the system has chosen one for you and there is a 50%
jpayne@69 316 chance of it being out by one hour. For some applications, this does
jpayne@69 317 not matter. However, if you are trying to schedule meetings with people
jpayne@69 318 in different timezones or analyze log files it is not acceptable.
jpayne@69 319
jpayne@69 320 The best and simplest solution is to stick with using UTC. The pytz
jpayne@69 321 package encourages using UTC for internal timezone representation by
jpayne@69 322 including a special UTC implementation based on the standard Python
jpayne@69 323 reference implementation in the Python documentation.
jpayne@69 324
jpayne@69 325 The UTC timezone unpickles to be the same instance, and pickles to a
jpayne@69 326 smaller size than other pytz tzinfo instances. The UTC implementation
jpayne@69 327 can be obtained as pytz.utc, pytz.UTC, or pytz.timezone('UTC').
jpayne@69 328
jpayne@69 329 >>> import pickle, pytz
jpayne@69 330 >>> dt = datetime(2005, 3, 1, 14, 13, 21, tzinfo=utc)
jpayne@69 331 >>> naive = dt.replace(tzinfo=None)
jpayne@69 332 >>> p = pickle.dumps(dt, 1)
jpayne@69 333 >>> naive_p = pickle.dumps(naive, 1)
jpayne@69 334 >>> len(p) - len(naive_p)
jpayne@69 335 17
jpayne@69 336 >>> new = pickle.loads(p)
jpayne@69 337 >>> new == dt
jpayne@69 338 True
jpayne@69 339 >>> new is dt
jpayne@69 340 False
jpayne@69 341 >>> new.tzinfo is dt.tzinfo
jpayne@69 342 True
jpayne@69 343 >>> pytz.utc is pytz.UTC is pytz.timezone('UTC')
jpayne@69 344 True
jpayne@69 345
jpayne@69 346 Note that some other timezones are commonly thought of as the same (GMT,
jpayne@69 347 Greenwich, Universal, etc.). The definition of UTC is distinct from these
jpayne@69 348 other timezones, and they are not equivalent. For this reason, they will
jpayne@69 349 not compare the same in Python.
jpayne@69 350
jpayne@69 351 >>> utc == pytz.timezone('GMT')
jpayne@69 352 False
jpayne@69 353
jpayne@69 354 See the section `What is UTC`_, below.
jpayne@69 355
jpayne@69 356 If you insist on working with local times, this library provides a
jpayne@69 357 facility for constructing them unambiguously:
jpayne@69 358
jpayne@69 359 >>> loc_dt = datetime(2002, 10, 27, 1, 30, 00)
jpayne@69 360 >>> est_dt = eastern.localize(loc_dt, is_dst=True)
jpayne@69 361 >>> edt_dt = eastern.localize(loc_dt, is_dst=False)
jpayne@69 362 >>> print(est_dt.strftime(fmt) + ' / ' + edt_dt.strftime(fmt))
jpayne@69 363 2002-10-27 01:30:00 EDT-0400 / 2002-10-27 01:30:00 EST-0500
jpayne@69 364
jpayne@69 365 If you pass None as the is_dst flag to localize(), pytz will refuse to
jpayne@69 366 guess and raise exceptions if you try to build ambiguous or non-existent
jpayne@69 367 times.
jpayne@69 368
jpayne@69 369 For example, 1:30am on 27th Oct 2002 happened twice in the US/Eastern
jpayne@69 370 timezone when the clocks where put back at the end of Daylight Saving
jpayne@69 371 Time:
jpayne@69 372
jpayne@69 373 >>> dt = datetime(2002, 10, 27, 1, 30, 00)
jpayne@69 374 >>> try:
jpayne@69 375 ... eastern.localize(dt, is_dst=None)
jpayne@69 376 ... except pytz.exceptions.AmbiguousTimeError:
jpayne@69 377 ... print('pytz.exceptions.AmbiguousTimeError: %s' % dt)
jpayne@69 378 pytz.exceptions.AmbiguousTimeError: 2002-10-27 01:30:00
jpayne@69 379
jpayne@69 380 Similarly, 2:30am on 7th April 2002 never happened at all in the
jpayne@69 381 US/Eastern timezone, as the clocks where put forward at 2:00am skipping
jpayne@69 382 the entire hour:
jpayne@69 383
jpayne@69 384 >>> dt = datetime(2002, 4, 7, 2, 30, 00)
jpayne@69 385 >>> try:
jpayne@69 386 ... eastern.localize(dt, is_dst=None)
jpayne@69 387 ... except pytz.exceptions.NonExistentTimeError:
jpayne@69 388 ... print('pytz.exceptions.NonExistentTimeError: %s' % dt)
jpayne@69 389 pytz.exceptions.NonExistentTimeError: 2002-04-07 02:30:00
jpayne@69 390
jpayne@69 391 Both of these exceptions share a common base class to make error handling
jpayne@69 392 easier:
jpayne@69 393
jpayne@69 394 >>> isinstance(pytz.AmbiguousTimeError(), pytz.InvalidTimeError)
jpayne@69 395 True
jpayne@69 396 >>> isinstance(pytz.NonExistentTimeError(), pytz.InvalidTimeError)
jpayne@69 397 True
jpayne@69 398
jpayne@69 399
jpayne@69 400 A special case is where countries change their timezone definitions
jpayne@69 401 with no daylight savings time switch. For example, in 1915 Warsaw
jpayne@69 402 switched from Warsaw time to Central European time with no daylight savings
jpayne@69 403 transition. So at the stroke of midnight on August 5th 1915 the clocks
jpayne@69 404 were wound back 24 minutes creating an ambiguous time period that cannot
jpayne@69 405 be specified without referring to the timezone abbreviation or the
jpayne@69 406 actual UTC offset. In this case midnight happened twice, neither time
jpayne@69 407 during a daylight saving time period. pytz handles this transition by
jpayne@69 408 treating the ambiguous period before the switch as daylight savings
jpayne@69 409 time, and the ambiguous period after as standard time.
jpayne@69 410
jpayne@69 411
jpayne@69 412 >>> warsaw = pytz.timezone('Europe/Warsaw')
jpayne@69 413 >>> amb_dt1 = warsaw.localize(datetime(1915, 8, 4, 23, 59, 59), is_dst=True)
jpayne@69 414 >>> amb_dt1.strftime(fmt)
jpayne@69 415 '1915-08-04 23:59:59 WMT+0124'
jpayne@69 416 >>> amb_dt2 = warsaw.localize(datetime(1915, 8, 4, 23, 59, 59), is_dst=False)
jpayne@69 417 >>> amb_dt2.strftime(fmt)
jpayne@69 418 '1915-08-04 23:59:59 CET+0100'
jpayne@69 419 >>> switch_dt = warsaw.localize(datetime(1915, 8, 5, 00, 00, 00), is_dst=False)
jpayne@69 420 >>> switch_dt.strftime(fmt)
jpayne@69 421 '1915-08-05 00:00:00 CET+0100'
jpayne@69 422 >>> str(switch_dt - amb_dt1)
jpayne@69 423 '0:24:01'
jpayne@69 424 >>> str(switch_dt - amb_dt2)
jpayne@69 425 '0:00:01'
jpayne@69 426
jpayne@69 427 The best way of creating a time during an ambiguous time period is
jpayne@69 428 by converting from another timezone such as UTC:
jpayne@69 429
jpayne@69 430 >>> utc_dt = datetime(1915, 8, 4, 22, 36, tzinfo=pytz.utc)
jpayne@69 431 >>> utc_dt.astimezone(warsaw).strftime(fmt)
jpayne@69 432 '1915-08-04 23:36:00 CET+0100'
jpayne@69 433
jpayne@69 434 The standard Python way of handling all these ambiguities is not to
jpayne@69 435 handle them, such as demonstrated in this example using the US/Eastern
jpayne@69 436 timezone definition from the Python documentation (Note that this
jpayne@69 437 implementation only works for dates between 1987 and 2006 - it is
jpayne@69 438 included for tests only!):
jpayne@69 439
jpayne@69 440 >>> from pytz.reference import Eastern # pytz.reference only for tests
jpayne@69 441 >>> dt = datetime(2002, 10, 27, 0, 30, tzinfo=Eastern)
jpayne@69 442 >>> str(dt)
jpayne@69 443 '2002-10-27 00:30:00-04:00'
jpayne@69 444 >>> str(dt + timedelta(hours=1))
jpayne@69 445 '2002-10-27 01:30:00-05:00'
jpayne@69 446 >>> str(dt + timedelta(hours=2))
jpayne@69 447 '2002-10-27 02:30:00-05:00'
jpayne@69 448 >>> str(dt + timedelta(hours=3))
jpayne@69 449 '2002-10-27 03:30:00-05:00'
jpayne@69 450
jpayne@69 451 Notice the first two results? At first glance you might think they are
jpayne@69 452 correct, but taking the UTC offset into account you find that they are
jpayne@69 453 actually two hours appart instead of the 1 hour we asked for.
jpayne@69 454
jpayne@69 455 >>> from pytz.reference import UTC # pytz.reference only for tests
jpayne@69 456 >>> str(dt.astimezone(UTC))
jpayne@69 457 '2002-10-27 04:30:00+00:00'
jpayne@69 458 >>> str((dt + timedelta(hours=1)).astimezone(UTC))
jpayne@69 459 '2002-10-27 06:30:00+00:00'
jpayne@69 460
jpayne@69 461
jpayne@69 462 Country Information
jpayne@69 463 ~~~~~~~~~~~~~~~~~~~
jpayne@69 464
jpayne@69 465 A mechanism is provided to access the timezones commonly in use
jpayne@69 466 for a particular country, looked up using the ISO 3166 country code.
jpayne@69 467 It returns a list of strings that can be used to retrieve the relevant
jpayne@69 468 tzinfo instance using ``pytz.timezone()``:
jpayne@69 469
jpayne@69 470 >>> print(' '.join(pytz.country_timezones['nz']))
jpayne@69 471 Pacific/Auckland Pacific/Chatham
jpayne@69 472
jpayne@69 473 The Olson database comes with a ISO 3166 country code to English country
jpayne@69 474 name mapping that pytz exposes as a dictionary:
jpayne@69 475
jpayne@69 476 >>> print(pytz.country_names['nz'])
jpayne@69 477 New Zealand
jpayne@69 478
jpayne@69 479
jpayne@69 480 What is UTC
jpayne@69 481 ~~~~~~~~~~~
jpayne@69 482
jpayne@69 483 'UTC' is `Coordinated Universal Time`_. It is a successor to, but distinct
jpayne@69 484 from, Greenwich Mean Time (GMT) and the various definitions of Universal
jpayne@69 485 Time. UTC is now the worldwide standard for regulating clocks and time
jpayne@69 486 measurement.
jpayne@69 487
jpayne@69 488 All other timezones are defined relative to UTC, and include offsets like
jpayne@69 489 UTC+0800 - hours to add or subtract from UTC to derive the local time. No
jpayne@69 490 daylight saving time occurs in UTC, making it a useful timezone to perform
jpayne@69 491 date arithmetic without worrying about the confusion and ambiguities caused
jpayne@69 492 by daylight saving time transitions, your country changing its timezone, or
jpayne@69 493 mobile computers that roam through multiple timezones.
jpayne@69 494
jpayne@69 495 .. _Coordinated Universal Time: https://en.wikipedia.org/wiki/Coordinated_Universal_Time
jpayne@69 496
jpayne@69 497
jpayne@69 498 Helpers
jpayne@69 499 ~~~~~~~
jpayne@69 500
jpayne@69 501 There are two lists of timezones provided.
jpayne@69 502
jpayne@69 503 ``all_timezones`` is the exhaustive list of the timezone names that can
jpayne@69 504 be used.
jpayne@69 505
jpayne@69 506 >>> from pytz import all_timezones
jpayne@69 507 >>> len(all_timezones) >= 500
jpayne@69 508 True
jpayne@69 509 >>> 'Etc/Greenwich' in all_timezones
jpayne@69 510 True
jpayne@69 511
jpayne@69 512 ``common_timezones`` is a list of useful, current timezones. It doesn't
jpayne@69 513 contain deprecated zones or historical zones, except for a few I've
jpayne@69 514 deemed in common usage, such as US/Eastern (open a bug report if you
jpayne@69 515 think other timezones are deserving of being included here). It is also
jpayne@69 516 a sequence of strings.
jpayne@69 517
jpayne@69 518 >>> from pytz import common_timezones
jpayne@69 519 >>> len(common_timezones) < len(all_timezones)
jpayne@69 520 True
jpayne@69 521 >>> 'Etc/Greenwich' in common_timezones
jpayne@69 522 False
jpayne@69 523 >>> 'Australia/Melbourne' in common_timezones
jpayne@69 524 True
jpayne@69 525 >>> 'US/Eastern' in common_timezones
jpayne@69 526 True
jpayne@69 527 >>> 'Canada/Eastern' in common_timezones
jpayne@69 528 True
jpayne@69 529 >>> 'Australia/Yancowinna' in all_timezones
jpayne@69 530 True
jpayne@69 531 >>> 'Australia/Yancowinna' in common_timezones
jpayne@69 532 False
jpayne@69 533
jpayne@69 534 Both ``common_timezones`` and ``all_timezones`` are alphabetically
jpayne@69 535 sorted:
jpayne@69 536
jpayne@69 537 >>> common_timezones_dupe = common_timezones[:]
jpayne@69 538 >>> common_timezones_dupe.sort()
jpayne@69 539 >>> common_timezones == common_timezones_dupe
jpayne@69 540 True
jpayne@69 541 >>> all_timezones_dupe = all_timezones[:]
jpayne@69 542 >>> all_timezones_dupe.sort()
jpayne@69 543 >>> all_timezones == all_timezones_dupe
jpayne@69 544 True
jpayne@69 545
jpayne@69 546 ``all_timezones`` and ``common_timezones`` are also available as sets.
jpayne@69 547
jpayne@69 548 >>> from pytz import all_timezones_set, common_timezones_set
jpayne@69 549 >>> 'US/Eastern' in all_timezones_set
jpayne@69 550 True
jpayne@69 551 >>> 'US/Eastern' in common_timezones_set
jpayne@69 552 True
jpayne@69 553 >>> 'Australia/Victoria' in common_timezones_set
jpayne@69 554 False
jpayne@69 555
jpayne@69 556 You can also retrieve lists of timezones used by particular countries
jpayne@69 557 using the ``country_timezones()`` function. It requires an ISO-3166
jpayne@69 558 two letter country code.
jpayne@69 559
jpayne@69 560 >>> from pytz import country_timezones
jpayne@69 561 >>> print(' '.join(country_timezones('ch')))
jpayne@69 562 Europe/Zurich
jpayne@69 563 >>> print(' '.join(country_timezones('CH')))
jpayne@69 564 Europe/Zurich
jpayne@69 565
jpayne@69 566
jpayne@69 567 Internationalization - i18n/l10n
jpayne@69 568 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
jpayne@69 569
jpayne@69 570 Pytz is an interface to the IANA database, which uses ASCII names. The `Unicode Consortium's Unicode Locales (CLDR) <http://cldr.unicode.org>`_
jpayne@69 571 project provides translations. Python packages such as
jpayne@69 572 `Babel <https://babel.pocoo.org/en/latest/api/dates.html#timezone-functionality>`_
jpayne@69 573 and Thomas Khyn's `l18n <https://pypi.org/project/l18n/>`_ package can be used
jpayne@69 574 to access these translations from Python.
jpayne@69 575
jpayne@69 576
jpayne@69 577 License
jpayne@69 578 ~~~~~~~
jpayne@69 579
jpayne@69 580 MIT license.
jpayne@69 581
jpayne@69 582 This code is also available as part of Zope 3 under the Zope Public
jpayne@69 583 License, Version 2.1 (ZPL).
jpayne@69 584
jpayne@69 585 I'm happy to relicense this code if necessary for inclusion in other
jpayne@69 586 open source projects.
jpayne@69 587
jpayne@69 588
jpayne@69 589 Latest Versions
jpayne@69 590 ~~~~~~~~~~~~~~~
jpayne@69 591
jpayne@69 592 This package will be updated after releases of the Olson timezone
jpayne@69 593 database. The latest version can be downloaded from the `Python Package
jpayne@69 594 Index <https://pypi.org/project/pytz/>`_. The code that is used
jpayne@69 595 to generate this distribution is hosted on Github and available
jpayne@69 596 using git::
jpayne@69 597
jpayne@69 598 git clone https://github.com/stub42/pytz.git
jpayne@69 599
jpayne@69 600 Announcements of new releases are made on
jpayne@69 601 `Launchpad <https://launchpad.net/pytz>`_, and the
jpayne@69 602 `Atom feed <http://feeds.launchpad.net/pytz/announcements.atom>`_
jpayne@69 603 hosted there.
jpayne@69 604
jpayne@69 605
jpayne@69 606 Bugs, Feature Requests & Patches
jpayne@69 607 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
jpayne@69 608
jpayne@69 609 Bugs should be reported on `Github <https://github.com/stub42/pytz/issues>`_.
jpayne@69 610 Feature requests are unlikely to be considered, and efforts instead directed
jpayne@69 611 to timezone support now built into Python or packages that work with it.
jpayne@69 612
jpayne@69 613
jpayne@69 614 Security Issues
jpayne@69 615 ~~~~~~~~~~~~~~~
jpayne@69 616
jpayne@69 617 Reports about security issues can be made via `Tidelift <https://tidelift.com/security>`_.
jpayne@69 618
jpayne@69 619
jpayne@69 620 Issues & Limitations
jpayne@69 621 ~~~~~~~~~~~~~~~~~~~~
jpayne@69 622
jpayne@69 623 - This project is in maintenance mode. Projects using Python 3.9 or later
jpayne@69 624 are best served by using the timezone functionaly now included in core
jpayne@69 625 Python and packages that work with it such as `tzdata <https://pypi.org/project/tzdata/>`_.
jpayne@69 626
jpayne@69 627 - Offsets from UTC are rounded to the nearest whole minute, so timezones
jpayne@69 628 such as Europe/Amsterdam pre 1937 will be up to 30 seconds out. This
jpayne@69 629 was a limitation of the Python datetime library.
jpayne@69 630
jpayne@69 631 - If you think a timezone definition is incorrect, I probably can't fix
jpayne@69 632 it. pytz is a direct translation of the Olson timezone database, and
jpayne@69 633 changes to the timezone definitions need to be made to this source.
jpayne@69 634 If you find errors they should be reported to the time zone mailing
jpayne@69 635 list, linked from http://www.iana.org/time-zones.
jpayne@69 636
jpayne@69 637
jpayne@69 638 Further Reading
jpayne@69 639 ~~~~~~~~~~~~~~~
jpayne@69 640
jpayne@69 641 More info than you want to know about timezones:
jpayne@69 642 https://data.iana.org/time-zones/tz-link.html
jpayne@69 643
jpayne@69 644
jpayne@69 645 Contact
jpayne@69 646 ~~~~~~~
jpayne@69 647
jpayne@69 648 Stuart Bishop <stuart@stuartbishop.net>