Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/lib/python3.8/site-packages/DateTime/pytz.txt @ 68:5028fdace37b

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 16:23:26 -0400
parents
children
rev   line source
jpayne@68 1 Pytz Support
jpayne@68 2 ============
jpayne@68 3
jpayne@68 4 Allows the pytz package to be used for time zone information. The
jpayne@68 5 advantage of using pytz is that it has a more complete and up to date
jpayne@68 6 time zone and daylight savings time database.
jpayne@68 7
jpayne@68 8 Usage
jpayne@68 9 -----
jpayne@68 10 You don't have to do anything special to make it work.
jpayne@68 11
jpayne@68 12 >>> from DateTime import DateTime, Timezones
jpayne@68 13 >>> d = DateTime('March 11, 2007 US/Eastern')
jpayne@68 14
jpayne@68 15 Daylight Savings
jpayne@68 16 ----------------
jpayne@68 17 In 2007 daylight savings time in the US was changed. The Energy Policy
jpayne@68 18 Act of 2005 mandates that DST will start on the second Sunday in March
jpayne@68 19 and end on the first Sunday in November.
jpayne@68 20
jpayne@68 21 In 2007, the start and stop dates are March 11 and November 4,
jpayne@68 22 respectively. These dates are different from previous DST start and
jpayne@68 23 stop dates. In 2006, the dates were the first Sunday in April (April
jpayne@68 24 2, 2006) and the last Sunday in October (October 29, 2006).
jpayne@68 25
jpayne@68 26 Let's make sure that DateTime can deal with this, since the primary
jpayne@68 27 motivation to use pytz for time zone information is the fact that it
jpayne@68 28 is kept up to date with daylight savings changes.
jpayne@68 29
jpayne@68 30 >>> DateTime('March 11, 2007 US/Eastern').tzoffset()
jpayne@68 31 -18000
jpayne@68 32 >>> DateTime('March 12, 2007 US/Eastern').tzoffset()
jpayne@68 33 -14400
jpayne@68 34 >>> DateTime('November 4, 2007 US/Eastern').tzoffset()
jpayne@68 35 -14400
jpayne@68 36 >>> DateTime('November 5, 2007 US/Eastern').tzoffset()
jpayne@68 37 -18000
jpayne@68 38
jpayne@68 39 Let's compare this to 2006.
jpayne@68 40
jpayne@68 41 >>> DateTime('April 2, 2006 US/Eastern').tzoffset()
jpayne@68 42 -18000
jpayne@68 43 >>> DateTime('April 3, 2006 US/Eastern').tzoffset()
jpayne@68 44 -14400
jpayne@68 45 >>> DateTime('October 29, 2006 US/Eastern').tzoffset()
jpayne@68 46 -14400
jpayne@68 47 >>> DateTime('October 30, 2006 US/Eastern').tzoffset()
jpayne@68 48 -18000
jpayne@68 49
jpayne@68 50 Time Zones
jpayne@68 51 ---------
jpayne@68 52 DateTime can use pytz's large database of time zones. Here are some
jpayne@68 53 examples:
jpayne@68 54
jpayne@68 55 >>> d = DateTime('Pacific/Kwajalein')
jpayne@68 56 >>> d = DateTime('America/Shiprock')
jpayne@68 57 >>> d = DateTime('Africa/Ouagadougou')
jpayne@68 58
jpayne@68 59 Of course pytz doesn't know about everything.
jpayne@68 60
jpayne@68 61 >>> from DateTime.interfaces import SyntaxError
jpayne@68 62 >>> try:
jpayne@68 63 ... d = DateTime('July 21, 1969 Moon/Eastern')
jpayne@68 64 ... print('fail')
jpayne@68 65 ... except SyntaxError:
jpayne@68 66 ... print('ok')
jpayne@68 67 ok
jpayne@68 68
jpayne@68 69 You can still use zone names that DateTime defines that aren't part of
jpayne@68 70 the pytz database.
jpayne@68 71
jpayne@68 72 >>> d = DateTime('eet')
jpayne@68 73 >>> d = DateTime('iceland')
jpayne@68 74
jpayne@68 75 These time zones use DateTimes database. So it's preferable to use the
jpayne@68 76 official time zone name.
jpayne@68 77
jpayne@68 78 One trickiness is that DateTime supports some zone name
jpayne@68 79 abbreviations. Some of these map to pytz names, so these abbreviations
jpayne@68 80 will give you time zone date from pytz. Notable among abbreviations
jpayne@68 81 that work this way are 'est', 'cst', 'mst', and 'pst'.
jpayne@68 82
jpayne@68 83 Let's verify that 'est' picks up the 2007 daylight savings time changes.
jpayne@68 84
jpayne@68 85 >>> DateTime('March 11, 2007 est').tzoffset()
jpayne@68 86 -18000
jpayne@68 87 >>> DateTime('March 12, 2007 est').tzoffset()
jpayne@68 88 -14400
jpayne@68 89 >>> DateTime('November 4, 2007 est').tzoffset()
jpayne@68 90 -14400
jpayne@68 91 >>> DateTime('November 5, 2007 est').tzoffset()
jpayne@68 92 -18000
jpayne@68 93
jpayne@68 94 You can get a list of time zones supported by calling the Timezones() function.
jpayne@68 95
jpayne@68 96 >>> Timezones() #doctest: +ELLIPSIS
jpayne@68 97 ['Africa/Abidjan', 'Africa/Accra', 'Africa/Addis_Ababa', ...]
jpayne@68 98
jpayne@68 99 Note that you can mess with this list without hurting things.
jpayne@68 100
jpayne@68 101 >>> t = Timezones()
jpayne@68 102 >>> t.remove('US/Eastern')
jpayne@68 103 >>> d = DateTime('US/Eastern')
jpayne@68 104
jpayne@68 105
jpayne@68 106 Internal Components
jpayne@68 107 -------------------
jpayne@68 108
jpayne@68 109 The following are tests of internal components.
jpayne@68 110
jpayne@68 111 Cache
jpayne@68 112 ~~~~~
jpayne@68 113
jpayne@68 114 The DateTime class uses a new time zone cache.
jpayne@68 115
jpayne@68 116 >>> from DateTime.DateTime import _TZINFO
jpayne@68 117 >>> _TZINFO #doctest: +ELLIPSIS
jpayne@68 118 <DateTime.pytz_support.PytzCache ...>
jpayne@68 119
jpayne@68 120 The cache maps time zone names to time zone instances.
jpayne@68 121
jpayne@68 122 >>> cache = _TZINFO
jpayne@68 123 >>> tz = cache['GMT+730']
jpayne@68 124 >>> tz = cache['US/Mountain']
jpayne@68 125
jpayne@68 126 The cache also must provide a few attributes for use by the DateTime
jpayne@68 127 class.
jpayne@68 128
jpayne@68 129 The _zlst attribute is a list of supported time zone names.
jpayne@68 130
jpayne@68 131 >>> cache._zlst #doctest: +ELLIPSIS
jpayne@68 132 ['Africa/Abidjan'... 'Africa/Accra'... 'IDLE'... 'NZST'... 'NZT'...]
jpayne@68 133
jpayne@68 134 The _zidx attribute is a list of lower-case and possibly abbreviated
jpayne@68 135 time zone names that can be mapped to official zone names.
jpayne@68 136
jpayne@68 137 >>> 'australia/yancowinna' in cache._zidx
jpayne@68 138 True
jpayne@68 139 >>> 'europe/isle_of_man' in cache._zidx
jpayne@68 140 True
jpayne@68 141 >>> 'gmt+0500' in cache._zidx
jpayne@68 142 True
jpayne@68 143
jpayne@68 144 Note that there are more items in _zidx than in _zlst since there are
jpayne@68 145 multiple names for some time zones.
jpayne@68 146
jpayne@68 147 >>> len(cache._zidx) > len(cache._zlst)
jpayne@68 148 True
jpayne@68 149
jpayne@68 150 Each entry in _zlst should also be present in _zidx in lower case form.
jpayne@68 151
jpayne@68 152 >>> for name in cache._zlst:
jpayne@68 153 ... if not name.lower() in cache._zidx:
jpayne@68 154 ... print("Error %s not in _zidx" % name.lower())
jpayne@68 155
jpayne@68 156 The _zmap attribute maps the names in _zidx to official names in _zlst.
jpayne@68 157
jpayne@68 158 >>> cache._zmap['africa/abidjan']
jpayne@68 159 'Africa/Abidjan'
jpayne@68 160 >>> cache._zmap['gmt+1']
jpayne@68 161 'GMT+1'
jpayne@68 162 >>> cache._zmap['gmt+0100']
jpayne@68 163 'GMT+1'
jpayne@68 164 >>> cache._zmap['utc']
jpayne@68 165 'UTC'
jpayne@68 166
jpayne@68 167 Let's make sure that _zmap and _zidx agree.
jpayne@68 168
jpayne@68 169 >>> idx = set(cache._zidx)
jpayne@68 170 >>> keys = set(cache._zmap.keys())
jpayne@68 171 >>> idx == keys
jpayne@68 172 True
jpayne@68 173
jpayne@68 174 Timezone objects
jpayne@68 175 ~~~~~~~~~~~~~~~~
jpayne@68 176 The timezone instances have only one public method info(). It returns
jpayne@68 177 a tuple of (offset, is_dst, name). The method takes a timestamp, which
jpayne@68 178 is used to determine dst information.
jpayne@68 179
jpayne@68 180 >>> t1 = DateTime('November 4, 00:00 2007 US/Mountain').timeTime()
jpayne@68 181 >>> t2 = DateTime('November 4, 02:00 2007 US/Mountain').timeTime()
jpayne@68 182 >>> tz.info(t1)
jpayne@68 183 (-21600, 1, 'MDT')
jpayne@68 184 >>> tz.info(t2)
jpayne@68 185 (-25200, 0, 'MST')
jpayne@68 186
jpayne@68 187 If you don't pass any arguments to info it provides daylight savings
jpayne@68 188 time information as of today.
jpayne@68 189
jpayne@68 190 >>> tz.info() in ((-21600, 1, 'MDT'), (-25200, 0, 'MST'))
jpayne@68 191 True
jpayne@68 192