Mercurial > repos > rliterman > csp2

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