blob: 7d2181e27ce4cdc4f2f432d97021986b513b560e [file] [log] [blame]
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +02001dateutil examples
2=================
3
4.. contents::
5
6relativedelta examples
7----------------------
8
9.. testsetup:: relativedelta
10
11 from datetime import *; from dateutil.relativedelta import *
12 import calendar
13 NOW = datetime(2003, 9, 17, 20, 54, 47, 282310)
14 TODAY = date(2003, 9, 17)
15
16Let's begin our trip::
17
18 >>> from datetime import *; from dateutil.relativedelta import *
19 >>> import calendar
20
21Store some values::
22
23 >>> NOW = datetime.now()
24 >>> TODAY = date.today()
25 >>> NOW
26 datetime.datetime(2003, 9, 17, 20, 54, 47, 282310)
27 >>> TODAY
28 datetime.date(2003, 9, 17)
29
30Next month
31
32.. doctest:: relativedelta
33
34 >>> NOW+relativedelta(months=+1)
35 datetime.datetime(2003, 10, 17, 20, 54, 47, 282310)
36
37Next month, plus one week.
38
39.. doctest:: relativedelta
40
41 >>> NOW+relativedelta(months=+1, weeks=+1)
42 datetime.datetime(2003, 10, 24, 20, 54, 47, 282310)
43
44Next month, plus one week, at 10am.
45
46.. doctest:: relativedelta
47
48 >>> TODAY+relativedelta(months=+1, weeks=+1, hour=10)
49 datetime.datetime(2003, 10, 24, 10, 0)
50
David Lehrian15ce30c2014-12-28 13:25:07 -080051Here is another example using an absolute relativedelta. Notice the use of
52year and month (both singular) which causes the values to be *replaced* in the
53original datetime rather than performing an arithmetic operation on them.
54
55.. doctest:: relativedelta
56
57 >>> NOW+relativedelta(year=1, month=1)
58 datetime(1, 1, 17, 20, 54, 47, 282310)
59
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +020060Let's try the other way around. Notice that the
61hour setting we get in the relativedelta is relative,
62since it's a difference, and the weeks parameter
63has gone.
64
65.. doctest:: relativedelta
66
67 >>> relativedelta(datetime(2003, 10, 24, 10, 0), TODAY)
68 relativedelta(months=+1, days=+7, hours=+10)
69
70One month before one year.
71
72.. doctest:: relativedelta
73
74 >>> NOW+relativedelta(years=+1, months=-1)
75 datetime.datetime(2004, 8, 17, 20, 54, 47, 282310)
76
77How does it handle months with different numbers of days?
78Notice that adding one month will never cross the month
79boundary.
80
81.. doctest:: relativedelta
82
83 >>> date(2003,1,27)+relativedelta(months=+1)
84 datetime.date(2003, 2, 27)
85 >>> date(2003,1,31)+relativedelta(months=+1)
86 datetime.date(2003, 2, 28)
87 >>> date(2003,1,31)+relativedelta(months=+2)
88 datetime.date(2003, 3, 31)
89
90The logic for years is the same, even on leap years.
91
92.. doctest:: relativedelta
93
94 >>> date(2000,2,28)+relativedelta(years=+1)
95 datetime.date(2001, 2, 28)
96 >>> date(2000,2,29)+relativedelta(years=+1)
97 datetime.date(2001, 2, 28)
98
99 >>> date(1999,2,28)+relativedelta(years=+1)
100 datetime.date(2000, 2, 28)
101 >>> date(1999,3,1)+relativedelta(years=+1)
102 datetime.date(2000, 3, 1)
103
104 >>> date(2001,2,28)+relativedelta(years=-1)
105 datetime.date(2000, 2, 28)
106 >>> date(2001,3,1)+relativedelta(years=-1)
107 datetime.date(2000, 3, 1)
108
109Next friday
110
111.. doctest:: relativedelta
112
113 >>> TODAY+relativedelta(weekday=FR)
114 datetime.date(2003, 9, 19)
115
116 >>> TODAY+relativedelta(weekday=calendar.FRIDAY)
117 datetime.date(2003, 9, 19)
118
119Last friday in this month.
120
121.. doctest:: relativedelta
122
123 >>> TODAY+relativedelta(day=31, weekday=FR(-1))
124 datetime.date(2003, 9, 26)
125
126Next wednesday (it's today!).
127
128.. doctest:: relativedelta
129
130 >>> TODAY+relativedelta(weekday=WE(+1))
131 datetime.date(2003, 9, 17)
132
133Next wednesday, but not today.
134
135.. doctest:: relativedelta
136
137 >>> TODAY+relativedelta(days=+1, weekday=WE(+1))
138 datetime.date(2003, 9, 24)
139
140Following
141[http://www.cl.cam.ac.uk/~mgk25/iso-time.html ISO year week number notation]
142find the first day of the 15th week of 1997.
143
144.. doctest:: relativedelta
145
146 >>> datetime(1997,1,1)+relativedelta(day=4, weekday=MO(-1), weeks=+14)
147 datetime.datetime(1997, 4, 7, 0, 0)
148
149How long ago has the millennium changed?
150
151.. doctest:: relativedelta
Alex Willmer1cb362f2015-09-06 10:31:26 +0100152 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200153
154 >>> relativedelta(NOW, date(2001,1,1))
155 relativedelta(years=+2, months=+8, days=+16,
156 hours=+20, minutes=+54, seconds=+47, microseconds=+282310)
157
158How old is John?
159
160.. doctest:: relativedelta
Alex Willmer1cb362f2015-09-06 10:31:26 +0100161 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200162
163 >>> johnbirthday = datetime(1978, 4, 5, 12, 0)
164 >>> relativedelta(NOW, johnbirthday)
165 relativedelta(years=+25, months=+5, days=+12,
166 hours=+8, minutes=+54, seconds=+47, microseconds=+282310)
167
168It works with dates too.
169
170.. doctest:: relativedelta
171
172 >>> relativedelta(TODAY, johnbirthday)
173 relativedelta(years=+25, months=+5, days=+11, hours=+12)
174
175Obtain today's date using the yearday:
176
177.. doctest:: relativedelta
178
179 >>> date(2003, 1, 1)+relativedelta(yearday=260)
180 datetime.date(2003, 9, 17)
181
182We can use today's date, since yearday should be absolute
183in the given year:
184
185.. doctest:: relativedelta
186
187 >>> TODAY+relativedelta(yearday=260)
188 datetime.date(2003, 9, 17)
189
190Last year it should be in the same day:
191
192.. doctest:: relativedelta
193
194 >>> date(2002, 1, 1)+relativedelta(yearday=260)
195 datetime.date(2002, 9, 17)
196
197But not in a leap year:
198
199.. doctest:: relativedelta
200
201 >>> date(2000, 1, 1)+relativedelta(yearday=260)
202 datetime.date(2000, 9, 16)
203
204We can use the non-leap year day to ignore this:
205
206.. doctest:: relativedelta
207
208 >>> date(2000, 1, 1)+relativedelta(nlyearday=260)
209 datetime.date(2000, 9, 17)
210
211rrule examples
212--------------
213These examples were converted from the RFC.
214
215Prepare the environment.
216
217.. testsetup:: rrule
218
219 from dateutil.rrule import *
220 from dateutil.parser import *
221 from datetime import *
222 import pprint
223 import sys
224 sys.displayhook = pprint.pprint
225
226.. doctest:: rrule
227
228 >>> from dateutil.rrule import *
229 >>> from dateutil.parser import *
230 >>> from datetime import *
231
232 >>> import pprint
233 >>> import sys
234 >>> sys.displayhook = pprint.pprint
235
236Daily, for 10 occurrences.
237
238.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100239 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200240
241 >>> list(rrule(DAILY, count=10,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100242 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200243 [datetime.datetime(1997, 9, 2, 9, 0),
244 datetime.datetime(1997, 9, 3, 9, 0),
245 datetime.datetime(1997, 9, 4, 9, 0),
246 datetime.datetime(1997, 9, 5, 9, 0),
247 datetime.datetime(1997, 9, 6, 9, 0),
248 datetime.datetime(1997, 9, 7, 9, 0),
249 datetime.datetime(1997, 9, 8, 9, 0),
250 datetime.datetime(1997, 9, 9, 9, 0),
251 datetime.datetime(1997, 9, 10, 9, 0),
252 datetime.datetime(1997, 9, 11, 9, 0)]
253
254Daily until December 24, 1997
255
256.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100257 :options: +NORMALIZE_WHITESPACE, +ELLIPSIS
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200258
259 >>> list(rrule(DAILY,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100260 ... dtstart=parse("19970902T090000"),
261 ... until=parse("19971224T000000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200262 [datetime.datetime(1997, 9, 2, 9, 0),
263 datetime.datetime(1997, 9, 3, 9, 0),
264 datetime.datetime(1997, 9, 4, 9, 0),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100265 ...
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200266 datetime.datetime(1997, 12, 21, 9, 0),
267 datetime.datetime(1997, 12, 22, 9, 0),
268 datetime.datetime(1997, 12, 23, 9, 0)]
269
270Every other day, 5 occurrences.
271
272.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100273 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200274
275 >>> list(rrule(DAILY, interval=2, count=5,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100276 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200277 [datetime.datetime(1997, 9, 2, 9, 0),
278 datetime.datetime(1997, 9, 4, 9, 0),
279 datetime.datetime(1997, 9, 6, 9, 0),
280 datetime.datetime(1997, 9, 8, 9, 0),
281 datetime.datetime(1997, 9, 10, 9, 0)]
282
283Every 10 days, 5 occurrences.
284
285.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100286 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200287
288 >>> list(rrule(DAILY, interval=10, count=5,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100289 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200290 [datetime.datetime(1997, 9, 2, 9, 0),
291 datetime.datetime(1997, 9, 12, 9, 0),
292 datetime.datetime(1997, 9, 22, 9, 0),
293 datetime.datetime(1997, 10, 2, 9, 0),
294 datetime.datetime(1997, 10, 12, 9, 0)]
295
296Everyday in January, for 3 years.
297
298.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100299 :options: +NORMALIZE_WHITESPACE, +ELLIPSIS
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200300
301 >>> list(rrule(YEARLY, bymonth=1, byweekday=range(7),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100302 ... dtstart=parse("19980101T090000"),
303 ... until=parse("20000131T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200304 [datetime.datetime(1998, 1, 1, 9, 0),
305 datetime.datetime(1998, 1, 2, 9, 0),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100306 ...
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200307 datetime.datetime(1998, 1, 30, 9, 0),
308 datetime.datetime(1998, 1, 31, 9, 0),
309 datetime.datetime(1999, 1, 1, 9, 0),
310 datetime.datetime(1999, 1, 2, 9, 0),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100311 ...
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200312 datetime.datetime(1999, 1, 30, 9, 0),
313 datetime.datetime(1999, 1, 31, 9, 0),
314 datetime.datetime(2000, 1, 1, 9, 0),
315 datetime.datetime(2000, 1, 2, 9, 0),
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200316 datetime.datetime(2000, 1, 29, 9, 0),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100317 ...
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200318 datetime.datetime(2000, 1, 31, 9, 0)]
319
320Same thing, in another way.
321
322.. doctest:: rrule
323
324 >>> list(rrule(DAILY, bymonth=1,
325 dtstart=parse("19980101T090000"),
326 until=parse("20000131T090000")))
327 (...)
328
329Weekly for 10 occurrences.
330
331.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100332 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200333
334 >>> list(rrule(WEEKLY, count=10,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100335 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200336 [datetime.datetime(1997, 9, 2, 9, 0),
337 datetime.datetime(1997, 9, 9, 9, 0),
338 datetime.datetime(1997, 9, 16, 9, 0),
339 datetime.datetime(1997, 9, 23, 9, 0),
340 datetime.datetime(1997, 9, 30, 9, 0),
341 datetime.datetime(1997, 10, 7, 9, 0),
342 datetime.datetime(1997, 10, 14, 9, 0),
343 datetime.datetime(1997, 10, 21, 9, 0),
344 datetime.datetime(1997, 10, 28, 9, 0),
345 datetime.datetime(1997, 11, 4, 9, 0)]
346
347Every other week, 6 occurrences.
348
349.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100350 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200351
352 >>> list(rrule(WEEKLY, interval=2, count=6,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100353 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200354 [datetime.datetime(1997, 9, 2, 9, 0),
355 datetime.datetime(1997, 9, 16, 9, 0),
356 datetime.datetime(1997, 9, 30, 9, 0),
357 datetime.datetime(1997, 10, 14, 9, 0),
358 datetime.datetime(1997, 10, 28, 9, 0),
359 datetime.datetime(1997, 11, 11, 9, 0)]
360
361Weekly on Tuesday and Thursday for 5 weeks.
362
363.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100364 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200365
366 >>> list(rrule(WEEKLY, count=10, wkst=SU, byweekday=(TU,TH),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100367 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200368 [datetime.datetime(1997, 9, 2, 9, 0),
369 datetime.datetime(1997, 9, 4, 9, 0),
370 datetime.datetime(1997, 9, 9, 9, 0),
371 datetime.datetime(1997, 9, 11, 9, 0),
372 datetime.datetime(1997, 9, 16, 9, 0),
373 datetime.datetime(1997, 9, 18, 9, 0),
374 datetime.datetime(1997, 9, 23, 9, 0),
375 datetime.datetime(1997, 9, 25, 9, 0),
376 datetime.datetime(1997, 9, 30, 9, 0),
377 datetime.datetime(1997, 10, 2, 9, 0)]
378
379Every other week on Tuesday and Thursday, for 8 occurrences.
380
381.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100382 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200383
384 >>> list(rrule(WEEKLY, interval=2, count=8,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100385 ... wkst=SU, byweekday=(TU,TH),
386 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200387 [datetime.datetime(1997, 9, 2, 9, 0),
388 datetime.datetime(1997, 9, 4, 9, 0),
389 datetime.datetime(1997, 9, 16, 9, 0),
390 datetime.datetime(1997, 9, 18, 9, 0),
391 datetime.datetime(1997, 9, 30, 9, 0),
392 datetime.datetime(1997, 10, 2, 9, 0),
393 datetime.datetime(1997, 10, 14, 9, 0),
394 datetime.datetime(1997, 10, 16, 9, 0)]
395
396Monthly on the 1st Friday for ten occurrences.
397
398.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100399 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200400
401 >>> list(rrule(MONTHLY, count=10, byweekday=FR(1),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100402 ... dtstart=parse("19970905T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200403 [datetime.datetime(1997, 9, 5, 9, 0),
404 datetime.datetime(1997, 10, 3, 9, 0),
405 datetime.datetime(1997, 11, 7, 9, 0),
406 datetime.datetime(1997, 12, 5, 9, 0),
407 datetime.datetime(1998, 1, 2, 9, 0),
408 datetime.datetime(1998, 2, 6, 9, 0),
409 datetime.datetime(1998, 3, 6, 9, 0),
410 datetime.datetime(1998, 4, 3, 9, 0),
411 datetime.datetime(1998, 5, 1, 9, 0),
412 datetime.datetime(1998, 6, 5, 9, 0)]
413
414Every other month on the 1st and last Sunday of the month for 10 occurrences.
415
416.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100417 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200418
419 >>> list(rrule(MONTHLY, interval=2, count=10,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100420 ... byweekday=(SU(1), SU(-1)),
421 ... dtstart=parse("19970907T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200422 [datetime.datetime(1997, 9, 7, 9, 0),
423 datetime.datetime(1997, 9, 28, 9, 0),
424 datetime.datetime(1997, 11, 2, 9, 0),
425 datetime.datetime(1997, 11, 30, 9, 0),
426 datetime.datetime(1998, 1, 4, 9, 0),
427 datetime.datetime(1998, 1, 25, 9, 0),
428 datetime.datetime(1998, 3, 1, 9, 0),
429 datetime.datetime(1998, 3, 29, 9, 0),
430 datetime.datetime(1998, 5, 3, 9, 0),
431 datetime.datetime(1998, 5, 31, 9, 0)]
432
433Monthly on the second to last Monday of the month for 6 months.
434
435.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100436 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200437
438 >>> list(rrule(MONTHLY, count=6, byweekday=MO(-2),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100439 ... dtstart=parse("19970922T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200440 [datetime.datetime(1997, 9, 22, 9, 0),
441 datetime.datetime(1997, 10, 20, 9, 0),
442 datetime.datetime(1997, 11, 17, 9, 0),
443 datetime.datetime(1997, 12, 22, 9, 0),
444 datetime.datetime(1998, 1, 19, 9, 0),
445 datetime.datetime(1998, 2, 16, 9, 0)]
446
447
448Monthly on the third to the last day of the month, for 6 months.
449
450.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100451 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200452
453 >>> list(rrule(MONTHLY, count=6, bymonthday=-3,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100454 ... dtstart=parse("19970928T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200455 [datetime.datetime(1997, 9, 28, 9, 0),
456 datetime.datetime(1997, 10, 29, 9, 0),
457 datetime.datetime(1997, 11, 28, 9, 0),
458 datetime.datetime(1997, 12, 29, 9, 0),
459 datetime.datetime(1998, 1, 29, 9, 0),
460 datetime.datetime(1998, 2, 26, 9, 0)]
461
462
463Monthly on the 2nd and 15th of the month for 5 occurrences.
464
465.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100466 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200467
468 >>> list(rrule(MONTHLY, count=5, bymonthday=(2,15),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100469 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200470 [datetime.datetime(1997, 9, 2, 9, 0),
471 datetime.datetime(1997, 9, 15, 9, 0),
472 datetime.datetime(1997, 10, 2, 9, 0),
473 datetime.datetime(1997, 10, 15, 9, 0),
474 datetime.datetime(1997, 11, 2, 9, 0)]
475
476
477Monthly on the first and last day of the month for 3 occurrences.
478
479.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100480 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200481
482 >>> list(rrule(MONTHLY, count=5, bymonthday=(-1,1,),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100483 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200484 [datetime.datetime(1997, 9, 30, 9, 0),
485 datetime.datetime(1997, 10, 1, 9, 0),
486 datetime.datetime(1997, 10, 31, 9, 0),
487 datetime.datetime(1997, 11, 1, 9, 0),
488 datetime.datetime(1997, 11, 30, 9, 0)]
489
490
491Every 18 months on the 10th thru 15th of the month for 10 occurrences.
492
493.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100494 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200495
496 >>> list(rrule(MONTHLY, interval=18, count=10,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100497 ... bymonthday=range(10,16),
498 ... dtstart=parse("19970910T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200499 [datetime.datetime(1997, 9, 10, 9, 0),
500 datetime.datetime(1997, 9, 11, 9, 0),
501 datetime.datetime(1997, 9, 12, 9, 0),
502 datetime.datetime(1997, 9, 13, 9, 0),
503 datetime.datetime(1997, 9, 14, 9, 0),
504 datetime.datetime(1997, 9, 15, 9, 0),
505 datetime.datetime(1999, 3, 10, 9, 0),
506 datetime.datetime(1999, 3, 11, 9, 0),
507 datetime.datetime(1999, 3, 12, 9, 0),
508 datetime.datetime(1999, 3, 13, 9, 0)]
509
510
511Every Tuesday, every other month, 6 occurences.
512
513.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100514 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200515
516 >>> list(rrule(MONTHLY, interval=2, count=6, byweekday=TU,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100517 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200518 [datetime.datetime(1997, 9, 2, 9, 0),
519 datetime.datetime(1997, 9, 9, 9, 0),
520 datetime.datetime(1997, 9, 16, 9, 0),
521 datetime.datetime(1997, 9, 23, 9, 0),
522 datetime.datetime(1997, 9, 30, 9, 0),
523 datetime.datetime(1997, 11, 4, 9, 0)]
524
525
526Yearly in June and July for 10 occurrences.
527
528.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100529 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200530
531 >>> list(rrule(YEARLY, count=4, bymonth=(6,7),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100532 ... dtstart=parse("19970610T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200533 [datetime.datetime(1997, 6, 10, 9, 0),
534 datetime.datetime(1997, 7, 10, 9, 0),
535 datetime.datetime(1998, 6, 10, 9, 0),
536 datetime.datetime(1998, 7, 10, 9, 0)]
537
538
539Every 3rd year on the 1st, 100th and 200th day for 4 occurrences.
540
541.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100542 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200543
544 >>> list(rrule(YEARLY, count=4, interval=3, byyearday=(1,100,200),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100545 ... dtstart=parse("19970101T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200546 [datetime.datetime(1997, 1, 1, 9, 0),
547 datetime.datetime(1997, 4, 10, 9, 0),
548 datetime.datetime(1997, 7, 19, 9, 0),
549 datetime.datetime(2000, 1, 1, 9, 0)]
550
551
552Every 20th Monday of the year, 3 occurrences.
553
554.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100555 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200556
557 >>> list(rrule(YEARLY, count=3, byweekday=MO(20),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100558 ... dtstart=parse("19970519T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200559 [datetime.datetime(1997, 5, 19, 9, 0),
560 datetime.datetime(1998, 5, 18, 9, 0),
561 datetime.datetime(1999, 5, 17, 9, 0)]
562
563
564Monday of week number 20 (where the default start of the week is Monday),
5653 occurrences.
566
567.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100568 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200569
570 >>> list(rrule(YEARLY, count=3, byweekno=20, byweekday=MO,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100571 ... dtstart=parse("19970512T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200572 [datetime.datetime(1997, 5, 12, 9, 0),
573 datetime.datetime(1998, 5, 11, 9, 0),
574 datetime.datetime(1999, 5, 17, 9, 0)]
575
576
577The week number 1 may be in the last year.
578
579.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100580 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200581
582 >>> list(rrule(WEEKLY, count=3, byweekno=1, byweekday=MO,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100583 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200584 [datetime.datetime(1997, 12, 29, 9, 0),
585 datetime.datetime(1999, 1, 4, 9, 0),
586 datetime.datetime(2000, 1, 3, 9, 0)]
587
588
589And the week numbers greater than 51 may be in the next year.
590
591.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100592 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200593
594 >>> list(rrule(WEEKLY, count=3, byweekno=52, byweekday=SU,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100595 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200596 [datetime.datetime(1997, 12, 28, 9, 0),
597 datetime.datetime(1998, 12, 27, 9, 0),
598 datetime.datetime(2000, 1, 2, 9, 0)]
599
600
601Only some years have week number 53:
602
603.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100604 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200605
606 >>> list(rrule(WEEKLY, count=3, byweekno=53, byweekday=MO,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100607 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200608 [datetime.datetime(1998, 12, 28, 9, 0),
609 datetime.datetime(2004, 12, 27, 9, 0),
610 datetime.datetime(2009, 12, 28, 9, 0)]
611
612
613Every Friday the 13th, 4 occurrences.
614
615.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100616 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200617
618 >>> list(rrule(YEARLY, count=4, byweekday=FR, bymonthday=13,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100619 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200620 [datetime.datetime(1998, 2, 13, 9, 0),
621 datetime.datetime(1998, 3, 13, 9, 0),
622 datetime.datetime(1998, 11, 13, 9, 0),
623 datetime.datetime(1999, 8, 13, 9, 0)]
624
625
626Every four years, the first Tuesday after a Monday in November,
6273 occurrences (U.S. Presidential Election day):
628
629.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100630 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200631
632 >>> list(rrule(YEARLY, interval=4, count=3, bymonth=11,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100633 ... byweekday=TU, bymonthday=(2,3,4,5,6,7,8),
634 ... dtstart=parse("19961105T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200635 [datetime.datetime(1996, 11, 5, 9, 0),
636 datetime.datetime(2000, 11, 7, 9, 0),
637 datetime.datetime(2004, 11, 2, 9, 0)]
638
639
640The 3rd instance into the month of one of Tuesday, Wednesday or
641Thursday, for the next 3 months:
642
643.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100644 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200645
646 >>> list(rrule(MONTHLY, count=3, byweekday=(TU,WE,TH),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100647 ... bysetpos=3, dtstart=parse("19970904T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200648 [datetime.datetime(1997, 9, 4, 9, 0),
649 datetime.datetime(1997, 10, 7, 9, 0),
650 datetime.datetime(1997, 11, 6, 9, 0)]
651
652
653The 2nd to last weekday of the month, 3 occurrences.
654
655.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100656 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200657
658 >>> list(rrule(MONTHLY, count=3, byweekday=(MO,TU,WE,TH,FR),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100659 ... bysetpos=-2, dtstart=parse("19970929T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200660 [datetime.datetime(1997, 9, 29, 9, 0),
661 datetime.datetime(1997, 10, 30, 9, 0),
662 datetime.datetime(1997, 11, 27, 9, 0)]
663
664
665Every 3 hours from 9:00 AM to 5:00 PM on a specific day.
666
667.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100668 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200669
670 >>> list(rrule(HOURLY, interval=3,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100671 ... dtstart=parse("19970902T090000"),
672 ... until=parse("19970902T170000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200673 [datetime.datetime(1997, 9, 2, 9, 0),
674 datetime.datetime(1997, 9, 2, 12, 0),
675 datetime.datetime(1997, 9, 2, 15, 0)]
676
677
678Every 15 minutes for 6 occurrences.
679
680.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100681 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200682
683 >>> list(rrule(MINUTELY, interval=15, count=6,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100684 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200685 [datetime.datetime(1997, 9, 2, 9, 0),
686 datetime.datetime(1997, 9, 2, 9, 15),
687 datetime.datetime(1997, 9, 2, 9, 30),
688 datetime.datetime(1997, 9, 2, 9, 45),
689 datetime.datetime(1997, 9, 2, 10, 0),
690 datetime.datetime(1997, 9, 2, 10, 15)]
691
692
693Every hour and a half for 4 occurrences.
694
695.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100696 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200697
698 >>> list(rrule(MINUTELY, interval=90, count=4,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100699 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200700 [datetime.datetime(1997, 9, 2, 9, 0),
701 datetime.datetime(1997, 9, 2, 10, 30),
702 datetime.datetime(1997, 9, 2, 12, 0),
703 datetime.datetime(1997, 9, 2, 13, 30)]
704
705
706Every 20 minutes from 9:00 AM to 4:40 PM for two days.
707
708.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100709 :options: +NORMALIZE_WHITESPACE, +ELLIPSIS
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200710
711 >>> list(rrule(MINUTELY, interval=20, count=48,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100712 ... byhour=range(9,17), byminute=(0,20,40),
713 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200714 [datetime.datetime(1997, 9, 2, 9, 0),
715 datetime.datetime(1997, 9, 2, 9, 20),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100716 ...
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200717 datetime.datetime(1997, 9, 2, 16, 20),
718 datetime.datetime(1997, 9, 2, 16, 40),
719 datetime.datetime(1997, 9, 3, 9, 0),
720 datetime.datetime(1997, 9, 3, 9, 20),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100721 ...
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200722 datetime.datetime(1997, 9, 3, 16, 20),
723 datetime.datetime(1997, 9, 3, 16, 40)]
724
725
726An example where the days generated makes a difference because of `wkst`.
727
728.. doctest:: rrule
Alex Willmer1cb362f2015-09-06 10:31:26 +0100729 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200730
731 >>> list(rrule(WEEKLY, interval=2, count=4,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100732 ... byweekday=(TU,SU), wkst=MO,
733 ... dtstart=parse("19970805T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200734 [datetime.datetime(1997, 8, 5, 9, 0),
735 datetime.datetime(1997, 8, 10, 9, 0),
736 datetime.datetime(1997, 8, 19, 9, 0),
737 datetime.datetime(1997, 8, 24, 9, 0)]
738
739 >>> list(rrule(WEEKLY, interval=2, count=4,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100740 ... byweekday=(TU,SU), wkst=SU,
741 ... dtstart=parse("19970805T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200742 [datetime.datetime(1997, 8, 5, 9, 0),
743 datetime.datetime(1997, 8, 17, 9, 0),
744 datetime.datetime(1997, 8, 19, 9, 0),
745 datetime.datetime(1997, 8, 31, 9, 0)]
746
747
748rruleset examples
749-----------------
750Daily, for 7 days, jumping Saturday and Sunday occurrences.
751
752.. doctest:: rruleset
Alex Willmer1cb362f2015-09-06 10:31:26 +0100753 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200754
755 >>> set = rruleset()
756 >>> set.rrule(rrule(DAILY, count=7,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100757 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200758 >>> set.exrule(rrule(YEARLY, byweekday=(SA,SU),
Alex Willmer1cb362f2015-09-06 10:31:26 +0100759 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200760 >>> list(set)
761 [datetime.datetime(1997, 9, 2, 9, 0),
762 datetime.datetime(1997, 9, 3, 9, 0),
763 datetime.datetime(1997, 9, 4, 9, 0),
764 datetime.datetime(1997, 9, 5, 9, 0),
765 datetime.datetime(1997, 9, 8, 9, 0)]
766
767
768Weekly, for 4 weeks, plus one time on day 7, and not on day 16.
769
770.. doctest:: rruleset
Alex Willmer1cb362f2015-09-06 10:31:26 +0100771 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200772
773 >>> set = rruleset()
774 >>> set.rrule(rrule(WEEKLY, count=4,
Alex Willmer1cb362f2015-09-06 10:31:26 +0100775 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200776 >>> set.rdate(datetime.datetime(1997, 9, 7, 9, 0))
777 >>> set.exdate(datetime.datetime(1997, 9, 16, 9, 0))
778 >>> list(set)
779 [datetime.datetime(1997, 9, 2, 9, 0),
780 datetime.datetime(1997, 9, 7, 9, 0),
781 datetime.datetime(1997, 9, 9, 9, 0),
782 datetime.datetime(1997, 9, 23, 9, 0)]
783
784
785rrulestr() examples
786-------------------
787
788Every 10 days, 5 occurrences.
789
790.. doctest:: rrulestr
Alex Willmer1cb362f2015-09-06 10:31:26 +0100791 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200792
793 >>> list(rrulestr("""
794 ... DTSTART:19970902T090000
795 ... RRULE:FREQ=DAILY;INTERVAL=10;COUNT=5
796 ... """))
797 [datetime.datetime(1997, 9, 2, 9, 0),
798 datetime.datetime(1997, 9, 12, 9, 0),
799 datetime.datetime(1997, 9, 22, 9, 0),
800 datetime.datetime(1997, 10, 2, 9, 0),
801 datetime.datetime(1997, 10, 12, 9, 0)]
802
803
804Same thing, but passing only the `RRULE` value.
805
806.. doctest:: rrulestr
Alex Willmer1cb362f2015-09-06 10:31:26 +0100807 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200808
809 >>> list(rrulestr("FREQ=DAILY;INTERVAL=10;COUNT=5",
Alex Willmer1cb362f2015-09-06 10:31:26 +0100810 ... dtstart=parse("19970902T090000")))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200811 [datetime.datetime(1997, 9, 2, 9, 0),
812 datetime.datetime(1997, 9, 12, 9, 0),
813 datetime.datetime(1997, 9, 22, 9, 0),
814 datetime.datetime(1997, 10, 2, 9, 0),
815 datetime.datetime(1997, 10, 12, 9, 0)]
816
817
818Notice that when using a single rule, it returns an
819`rrule` instance, unless `forceset` was used.
820
821.. doctest:: rrulestr
Alex Willmer1cb362f2015-09-06 10:31:26 +0100822 :options: +ELLIPSIS
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200823
824 >>> rrulestr("FREQ=DAILY;INTERVAL=10;COUNT=5")
Alex Willmer1cb362f2015-09-06 10:31:26 +0100825 <dateutil.rrule.rrule object at 0x...>
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200826
827 >>> rrulestr("""
828 ... DTSTART:19970902T090000
829 ... RRULE:FREQ=DAILY;INTERVAL=10;COUNT=5
830 ... """)
Alex Willmer1cb362f2015-09-06 10:31:26 +0100831 <dateutil.rrule.rrule object at 0x...>
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200832
833 >>> rrulestr("FREQ=DAILY;INTERVAL=10;COUNT=5", forceset=True)
Alex Willmer1cb362f2015-09-06 10:31:26 +0100834 <dateutil.rrule.rruleset object at 0x...>
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200835
836
837But when an `rruleset` is needed, it is automatically used.
838
839.. doctest:: rrulestr
Alex Willmer1cb362f2015-09-06 10:31:26 +0100840 :options: +ELLIPSIS
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200841
842 >>> rrulestr("""
843 ... DTSTART:19970902T090000
844 ... RRULE:FREQ=DAILY;INTERVAL=10;COUNT=5
845 ... RRULE:FREQ=DAILY;INTERVAL=5;COUNT=3
846 ... """)
Alex Willmer1cb362f2015-09-06 10:31:26 +0100847 <dateutil.rrule.rruleset object at 0x...>
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200848
849
850parse examples
851-----------
852The following code will prepare the environment:
853
854.. doctest:: tz
855
856 >>> from dateutil.parser import *
857 >>> from dateutil.tz import *
858 >>> from datetime import *
859 >>> TZOFFSETS = {"BRST": -10800}
860 >>> BRSTTZ = tzoffset(-10800, "BRST")
861 >>> DEFAULT = datetime(2003, 9, 25)
862
863
864Some simple examples based on the `date` command, using the
865`ZOFFSET` dictionary to provide the BRST timezone offset.
866
867.. doctest:: tz
Alex Willmer1cb362f2015-09-06 10:31:26 +0100868 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200869
870 >>> parse("Thu Sep 25 10:36:28 BRST 2003", tzinfos=TZOFFSETS)
871 datetime.datetime(2003, 9, 25, 10, 36, 28,
872 tzinfo=tzoffset('BRST', -10800))
873
874 >>> parse("2003 10:36:28 BRST 25 Sep Thu", tzinfos=TZOFFSETS)
875 datetime.datetime(2003, 9, 25, 10, 36, 28,
876 tzinfo=tzoffset('BRST', -10800))
877
878
879Notice that since BRST is my local timezone, parsing it without
880further timezone settings will yield a `tzlocal` timezone.
881
882.. doctest:: tz
883
884 >>> parse("Thu Sep 25 10:36:28 BRST 2003")
885 datetime.datetime(2003, 9, 25, 10, 36, 28, tzinfo=tzlocal())
886
887
888We can also ask to ignore the timezone explicitly:
889
890.. doctest:: tz
891
892 >>> parse("Thu Sep 25 10:36:28 BRST 2003", ignoretz=True)
893 datetime.datetime(2003, 9, 25, 10, 36, 28)
894
895
896That's the same as processing a string without timezone:
897
898.. doctest:: tz
899
900 >>> parse("Thu Sep 25 10:36:28 2003")
901 datetime.datetime(2003, 9, 25, 10, 36, 28)
902
903
904Without the year, but passing our `DEFAULT` datetime to return
905the same year, no mattering what year we currently are in:
906
907.. doctest:: tz
908
909 >>> parse("Thu Sep 25 10:36:28", default=DEFAULT)
910 datetime.datetime(2003, 9, 25, 10, 36, 28)
911
912
913Strip it further:
914
915.. doctest:: tz
916
917 >>> parse("Thu Sep 10:36:28", default=DEFAULT)
918 datetime.datetime(2003, 9, 25, 10, 36, 28)
919
920 >>> parse("Thu 10:36:28", default=DEFAULT)
921 datetime.datetime(2003, 9, 25, 10, 36, 28)
922
923 >>> parse("Thu 10:36", default=DEFAULT)
924 datetime.datetime(2003, 9, 25, 10, 36)
925
926 >>> parse("10:36", default=DEFAULT)
927 datetime.datetime(2003, 9, 25, 10, 36)
928 >>>
929
930
931Strip in a different way:
932
933.. doctest:: tz
934
935 >>> parse("Thu Sep 25 2003")
936 datetime.datetime(2003, 9, 25, 0, 0)
937
938 >>> parse("Sep 25 2003")
939 datetime.datetime(2003, 9, 25, 0, 0)
940
941 >>> parse("Sep 2003", default=DEFAULT)
942 datetime.datetime(2003, 9, 25, 0, 0)
943
944 >>> parse("Sep", default=DEFAULT)
945 datetime.datetime(2003, 9, 25, 0, 0)
946
947 >>> parse("2003", default=DEFAULT)
948 datetime.datetime(2003, 9, 25, 0, 0)
949
950
951Another format, based on `date -R` (RFC822):
952
953.. doctest:: tz
Alex Willmer1cb362f2015-09-06 10:31:26 +0100954 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200955
956 >>> parse("Thu, 25 Sep 2003 10:49:41 -0300")
957 datetime.datetime(2003, 9, 25, 10, 49, 41,
958 tzinfo=tzoffset(None, -10800))
959
960
961ISO format:
962
963.. doctest:: tz
Alex Willmer1cb362f2015-09-06 10:31:26 +0100964 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200965
966 >>> parse("2003-09-25T10:49:41.5-03:00")
967 datetime.datetime(2003, 9, 25, 10, 49, 41, 500000,
968 tzinfo=tzoffset(None, -10800))
969
970
971Some variations:
972
973.. doctest:: tz
974
975 >>> parse("2003-09-25T10:49:41")
976 datetime.datetime(2003, 9, 25, 10, 49, 41)
977
978 >>> parse("2003-09-25T10:49")
979 datetime.datetime(2003, 9, 25, 10, 49)
980
981 >>> parse("2003-09-25T10")
982 datetime.datetime(2003, 9, 25, 10, 0)
983
984 >>> parse("2003-09-25")
985 datetime.datetime(2003, 9, 25, 0, 0)
986
987
988ISO format, without separators:
989
990.. doctest:: tz
Alex Willmer1cb362f2015-09-06 10:31:26 +0100991 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +0200992
993 >>> parse("20030925T104941.5-0300")
994 datetime.datetime(2003, 9, 25, 10, 49, 41, 500000,
995 tzinfo=tzinfo=tzoffset(None, -10800))
996
997 >>> parse("20030925T104941-0300")
998 datetime.datetime(2003, 9, 25, 10, 49, 41,
999 tzinfo=tzoffset(None, -10800))
1000
1001 >>> parse("20030925T104941")
1002 datetime.datetime(2003, 9, 25, 10, 49, 41)
1003
1004 >>> parse("20030925T1049")
1005 datetime.datetime(2003, 9, 25, 10, 49)
1006
1007 >>> parse("20030925T10")
1008 datetime.datetime(2003, 9, 25, 10, 0)
1009
1010 >>> parse("20030925")
1011 datetime.datetime(2003, 9, 25, 0, 0)
1012
1013
1014Everything together.
1015
1016.. doctest:: tz
1017
1018 >>> parse("199709020900")
1019 datetime.datetime(1997, 9, 2, 9, 0)
1020 >>> parse("19970902090059")
1021 datetime.datetime(1997, 9, 2, 9, 0, 59)
1022
1023
1024Different date orderings:
1025
1026.. doctest:: tz
1027
1028 >>> parse("2003-09-25")
1029 datetime.datetime(2003, 9, 25, 0, 0)
1030
1031 >>> parse("2003-Sep-25")
1032 datetime.datetime(2003, 9, 25, 0, 0)
1033
1034 >>> parse("25-Sep-2003")
1035 datetime.datetime(2003, 9, 25, 0, 0)
1036
1037 >>> parse("Sep-25-2003")
1038 datetime.datetime(2003, 9, 25, 0, 0)
1039
1040 >>> parse("09-25-2003")
1041 datetime.datetime(2003, 9, 25, 0, 0)
1042
1043 >>> parse("25-09-2003")
1044 datetime.datetime(2003, 9, 25, 0, 0)
1045
1046
1047Check some ambiguous dates:
1048
1049.. doctest:: tz
1050
1051 >>> parse("10-09-2003")
1052 datetime.datetime(2003, 10, 9, 0, 0)
1053
1054 >>> parse("10-09-2003", dayfirst=True)
1055 datetime.datetime(2003, 9, 10, 0, 0)
1056
1057 >>> parse("10-09-03")
1058 datetime.datetime(2003, 10, 9, 0, 0)
1059
1060 >>> parse("10-09-03", yearfirst=True)
1061 datetime.datetime(2010, 9, 3, 0, 0)
1062
1063
1064Other date separators are allowed:
1065
1066.. doctest:: tz
1067
1068 >>> parse("2003.Sep.25")
1069 datetime.datetime(2003, 9, 25, 0, 0)
1070
1071 >>> parse("2003/09/25")
1072 datetime.datetime(2003, 9, 25, 0, 0)
1073
1074
1075Even with spaces:
1076
1077.. doctest:: tz
1078
1079 >>> parse("2003 Sep 25")
1080 datetime.datetime(2003, 9, 25, 0, 0)
1081
1082 >>> parse("2003 09 25")
1083 datetime.datetime(2003, 9, 25, 0, 0)
1084
1085
1086Hours with letters work:
1087
1088.. doctest:: tz
1089
1090 >>> parse("10h36m28.5s", default=DEFAULT)
1091 datetime.datetime(2003, 9, 25, 10, 36, 28, 500000)
1092
1093 >>> parse("01s02h03m", default=DEFAULT)
1094 datetime.datetime(2003, 9, 25, 2, 3, 1)
1095
1096 >>> parse("01h02m03", default=DEFAULT)
1097 datetime.datetime(2003, 9, 3, 1, 2)
1098
1099 >>> parse("01h02", default=DEFAULT)
1100 datetime.datetime(2003, 9, 2, 1, 0)
1101
1102 >>> parse("01h02s", default=DEFAULT)
1103 datetime.datetime(2003, 9, 25, 1, 0, 2)
1104
1105
1106With AM/PM:
1107
1108.. doctest:: tz
1109
1110 >>> parse("10h am", default=DEFAULT)
1111 datetime.datetime(2003, 9, 25, 10, 0)
1112
1113 >>> parse("10pm", default=DEFAULT)
1114 datetime.datetime(2003, 9, 25, 22, 0)
1115
1116 >>> parse("12:00am", default=DEFAULT)
1117 datetime.datetime(2003, 9, 25, 0, 0)
1118
1119 >>> parse("12pm", default=DEFAULT)
1120 datetime.datetime(2003, 9, 25, 12, 0)
1121
1122
1123Some special treating for ''pertain'' relations:
1124
1125.. doctest:: tz
1126
1127 >>> parse("Sep 03", default=DEFAULT)
1128 datetime.datetime(2003, 9, 3, 0, 0)
1129
1130 >>> parse("Sep of 03", default=DEFAULT)
1131 datetime.datetime(2003, 9, 25, 0, 0)
1132
1133
1134Fuzzy parsing:
1135
1136.. doctest:: tz
Alex Willmer1cb362f2015-09-06 10:31:26 +01001137 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +02001138
1139 >>> s = "Today is 25 of September of 2003, exactly " \
1140 ... "at 10:49:41 with timezone -03:00."
1141 >>> parse(s, fuzzy=True)
1142 datetime.datetime(2003, 9, 25, 10, 49, 41,
1143 tzinfo=tzoffset(None, -10800))
1144
1145
1146Other random formats:
1147
1148.. doctest:: tz
1149
1150 >>> parse("Wed, July 10, '96")
1151 datetime.datetime(1996, 7, 10, 0, 0)
1152
1153 >>> parse("1996.07.10 AD at 15:08:56 PDT", ignoretz=True)
1154 datetime.datetime(1996, 7, 10, 15, 8, 56)
1155
1156 >>> parse("Tuesday, April 12, 1952 AD 3:30:42pm PST", ignoretz=True)
1157 datetime.datetime(1952, 4, 12, 15, 30, 42)
1158
1159 >>> parse("November 5, 1994, 8:15:30 am EST", ignoretz=True)
1160 datetime.datetime(1994, 11, 5, 8, 15, 30)
1161
1162 >>> parse("3rd of May 2001")
1163 datetime.datetime(2001, 5, 3, 0, 0)
1164
1165 >>> parse("5:50 A.M. on June 13, 1990")
1166 datetime.datetime(1990, 6, 13, 5, 50)
1167
1168
1169tzutc examples
1170--------------
1171
1172.. doctest:: tzutc
1173
1174 >>> from datetime import *
1175 >>> from dateutil.tz import *
1176
1177 >>> datetime.now()
1178 datetime.datetime(2003, 9, 27, 9, 40, 1, 521290)
1179
1180 >>> datetime.now(tzutc())
1181 datetime.datetime(2003, 9, 27, 12, 40, 12, 156379, tzinfo=tzutc())
1182
1183 >>> datetime.now(tzutc()).tzname()
1184 'UTC'
1185
1186
1187tzoffset examples
1188-----------------
1189
1190.. doctest:: tzoffset
Alex Willmer1cb362f2015-09-06 10:31:26 +01001191 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +02001192
1193 >>> from datetime import *
1194 >>> from dateutil.tz import *
1195
1196 >>> datetime.now(tzoffset("BRST", -10800))
1197 datetime.datetime(2003, 9, 27, 9, 52, 43, 624904,
1198 tzinfo=tzinfo=tzoffset('BRST', -10800))
1199
1200 >>> datetime.now(tzoffset("BRST", -10800)).tzname()
1201 'BRST'
1202
1203 >>> datetime.now(tzoffset("BRST", -10800)).astimezone(tzutc())
1204 datetime.datetime(2003, 9, 27, 12, 53, 11, 446419,
1205 tzinfo=tzutc())
1206
1207
1208tzlocal examples
1209----------------
1210
1211.. doctest:: tzlocal
1212
1213 >>> from datetime import *
1214 >>> from dateutil.tz import *
1215
1216 >>> datetime.now(tzlocal())
1217 datetime.datetime(2003, 9, 27, 10, 1, 43, 673605,
1218 tzinfo=tzlocal())
1219
1220 >>> datetime.now(tzlocal()).tzname()
1221 'BRST'
1222
1223 >>> datetime.now(tzlocal()).astimezone(tzoffset(None, 0))
1224 datetime.datetime(2003, 9, 27, 13, 3, 0, 11493,
1225 tzinfo=tzoffset(None, 0))
1226
1227
1228tzstr examples
1229--------------
1230Here are examples of the recognized formats:
1231
1232 * `EST5EDT`
1233 * `EST5EDT,4,0,6,7200,10,0,26,7200,3600`
1234 * `EST5EDT,4,1,0,7200,10,-1,0,7200,3600`
1235 * `EST5EDT4,M4.1.0/02:00:00,M10-5-0/02:00`
1236 * `EST5EDT4,95/02:00:00,298/02:00`
1237 * `EST5EDT4,J96/02:00:00,J299/02:00`
1238
1239Notice that if daylight information is not present, but a
1240daylight abbreviation was provided, `tzstr` will follow the
1241convention of using the first sunday of April to start daylight
1242saving, and the last sunday of October to end it. If start or
1243end time is not present, 2AM will be used, and if the daylight
1244offset is not present, the standard offset plus one hour will
1245be used. This convention is the same as used in the GNU libc.
1246
1247This also means that some of the above examples are exactly
1248equivalent, and all of these examples are equivalent
1249in the year of 2003.
1250
1251Here is the example mentioned in the
1252
1253[http://www.python.org/doc/current/lib/module-time.html time module documentation].
1254
1255
1256.. doctest:: tzstr
1257
1258 >>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
1259 >>> time.tzset()
1260 >>> time.strftime('%X %x %Z')
1261 '02:07:36 05/08/03 EDT'
1262 >>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
1263 >>> time.tzset()
1264 >>> time.strftime('%X %x %Z')
1265 '16:08:12 05/08/03 AEST'
1266
1267
1268And here is an example showing the same information using `tzstr`,
1269without touching system settings.
1270
1271.. doctest:: tzstr
1272
1273 >>> tz1 = tzstr('EST+05EDT,M4.1.0,M10.5.0')
1274 >>> tz2 = tzstr('AEST-10AEDT-11,M10.5.0,M3.5.0')
1275 >>> dt = datetime(2003, 5, 8, 2, 7, 36, tzinfo=tz1)
1276 >>> dt.strftime('%X %x %Z')
1277 '02:07:36 05/08/03 EDT'
1278 >>> dt.astimezone(tz2).strftime('%X %x %Z')
1279 '16:07:36 05/08/03 AEST'
1280
1281
1282Are these really equivalent?
1283
1284.. doctest:: tzstr
1285
1286 >>> tzstr('EST5EDT') == tzstr('EST5EDT,4,1,0,7200,10,-1,0,7200,3600')
1287 True
1288
1289
1290Check the daylight limit.
1291
1292.. doctest:: tzstr
1293
1294 >>> datetime(2003, 4, 6, 1, 59, tzinfo=tz).tzname()
1295 'EST'
1296 >>> datetime(2003, 4, 6, 2, 00, tzinfo=tz).tzname()
1297 'EDT'
1298 >>> datetime(2003, 10, 26, 0, 59, tzinfo=tz).tzname()
1299 'EDT'
1300 >>> datetime(2003, 10, 26, 1, 00, tzinfo=tz).tzname()
1301 'EST'
1302
1303
1304tzrange examples
1305----------------
1306
1307.. doctest:: tzrange
1308
1309 >>> tzstr('EST5EDT') == tzrange("EST", -18000, "EDT")
1310 True
1311
1312 >>> from dateutil.relativedelta import *
1313 >>> range1 = tzrange("EST", -18000, "EDT")
1314 >>> range2 = tzrange("EST", -18000, "EDT", -14400,
1315 ... relativedelta(hours=+2, month=4, day=1,
Alex Willmer1cb362f2015-09-06 10:31:26 +01001316 ... weekday=SU(+1)),
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +02001317 ... relativedelta(hours=+1, month=10, day=31,
Alex Willmer1cb362f2015-09-06 10:31:26 +01001318 ... weekday=SU(-1)))
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +02001319 >>> tzstr('EST5EDT') == range1 == range2
1320 True
1321
1322
1323Notice a minor detail in the last example: while the DST should end
1324at 2AM, the delta will catch 1AM. That's because the daylight saving
1325time should end at 2AM standard time (the difference between STD and
1326DST is 1h in the given example) instead of the DST time. That's how
1327the `tzinfo` subtypes should deal with the extra hour that happens
1328when going back to the standard time. Check
1329
1330[http://www.python.org/doc/current/lib/datetime-tzinfo.html tzinfo documentation]
1331
1332for more information.
1333
1334tzfile examples
1335---------------
1336
1337.. doctest:: tzfile
Alex Willmer1cb362f2015-09-06 10:31:26 +01001338 :options: +NORMALIZE_WHITESPACE
Yaron de Leeuwdb52fc82014-11-29 18:04:03 +02001339
1340 >>> tz = tzfile("/etc/localtime")
1341 >>> datetime.now(tz)
1342 datetime.datetime(2003, 9, 27, 12, 3, 48, 392138,
1343 tzinfo=tzfile('/etc/localtime'))
1344
1345 >>> datetime.now(tz).astimezone(tzutc())
1346 datetime.datetime(2003, 9, 27, 15, 3, 53, 70863,
1347 tzinfo=tzutc())
1348
1349 >>> datetime.now(tz).tzname()
1350 'BRST'
1351 >>> datetime(2003, 1, 1, tzinfo=tz).tzname()
1352 'BRDT'
1353
1354
1355Check the daylight limit.
1356
1357.. doctest:: tzfile
1358
1359 >>> tz = tzfile('/usr/share/zoneinfo/EST5EDT')
1360 >>> datetime(2003, 4, 6, 1, 59, tzinfo=tz).tzname()
1361 'EST'
1362 >>> datetime(2003, 4, 6, 2, 00, tzinfo=tz).tzname()
1363 'EDT'
1364 >>> datetime(2003, 10, 26, 0, 59, tzinfo=tz).tzname()
1365 'EDT'
1366 >>> datetime(2003, 10, 26, 1, 00, tzinfo=tz).tzname()
1367 'EST'
1368
1369
1370tzical examples
1371---------------
1372Here is a sample file extracted from the RFC. This file defines
1373the `EST5EDT` timezone, and will be used in the following example.
1374
1375 BEGIN:VTIMEZONE
1376 TZID:US-Eastern
1377 LAST-MODIFIED:19870101T000000Z
1378 TZURL:http://zones.stds_r_us.net/tz/US-Eastern
1379 BEGIN:STANDARD
1380 DTSTART:19671029T020000
1381 RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
1382 TZOFFSETFROM:-0400
1383 TZOFFSETTO:-0500
1384 TZNAME:EST
1385 END:STANDARD
1386 BEGIN:DAYLIGHT
1387 DTSTART:19870405T020000
1388 RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
1389 TZOFFSETFROM:-0500
1390 TZOFFSETTO:-0400
1391 TZNAME:EDT
1392 END:DAYLIGHT
1393 END:VTIMEZONE
1394
1395And here is an example exploring a `tzical` type:
1396
1397.. doctest:: tzfile
1398
1399 >>> from dateutil.tz import *; from datetime import *
1400
1401 >>> tz = tzical('EST5EDT.ics')
1402 >>> tz.keys()
1403 ['US-Eastern']
1404
1405 >>> est = tz.get('US-Eastern')
1406 >>> est
1407 <tzicalvtz 'US-Eastern'>
1408
1409 >>> datetime.now(est)
1410 datetime.datetime(2003, 10, 6, 19, 44, 18, 667987,
1411 tzinfo=<tzicalvtz 'US-Eastern'>)
1412
1413 >>> est == tz.get()
1414 True
1415
1416
1417Let's check the daylight ranges, as usual:
1418
1419.. doctest:: tzfile
1420
1421 >>> datetime(2003, 4, 6, 1, 59, tzinfo=est).tzname()
1422 'EST'
1423 >>> datetime(2003, 4, 6, 2, 00, tzinfo=est).tzname()
1424 'EDT'
1425
1426 >>> datetime(2003, 10, 26, 0, 59, tzinfo=est).tzname()
1427 'EDT'
1428 >>> datetime(2003, 10, 26, 1, 00, tzinfo=est).tzname()
1429 'EST'
1430
1431
1432tzwin examples
1433--------------
1434
1435.. doctest:: tzwin
1436
1437 >>> tz = tzwin("E. South America Standard Time")
1438
1439
1440tzwinlocal examples
1441-------------------
1442
1443
1444.. doctest:: tzwinlocal
1445
1446 >>> tz = tzwinlocal()
1447
1448# vim:ts=4:sw=4:et