README 58 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970
  1. ## This file is in the moin format. The latest version is found
  2. ## at https://moin.conectiva.com.br/DateUtil
  3. == Contents ==
  4. [[TableOfContents]]
  5. == Description ==
  6. The '''dateutil''' module provides powerful extensions to
  7. the standard '''datetime''' module, available in Python 2.3+.
  8. == Features ==
  9. * Computing of relative deltas (next month, next year,
  10. next monday, last week of month, etc);
  11. * Computing of relative deltas between two given
  12. date and/or datetime objects;
  13. * Computing of dates based on very flexible recurrence rules,
  14. using a superset of the
  15. [ftp://ftp.rfc-editor.org/in-notes/rfc2445.txt iCalendar]
  16. specification. Parsing of RFC strings is supported as well.
  17. * Generic parsing of dates in almost any string format;
  18. * Timezone (tzinfo) implementations for tzfile(5) format
  19. files (/etc/localtime, /usr/share/zoneinfo, etc), TZ
  20. environment string (in all known formats), iCalendar
  21. format files, given ranges (with help from relative deltas),
  22. local machine timezone, fixed offset timezone, UTC timezone,
  23. and Windows registry-based time zones.
  24. * Internal up-to-date world timezone information based on
  25. Olson's database.
  26. * Computing of Easter Sunday dates for any given year,
  27. using Western, Orthodox or Julian algorithms;
  28. * More than 400 test cases.
  29. == Quick example ==
  30. Here's a snapshot, just to give an idea about the power of the
  31. package. For more examples, look at the documentation below.
  32. Suppose you want to know how much time is left, in
  33. years/months/days/etc, before the next easter happening on a
  34. year with a Friday 13th in August, and you want to get today's
  35. date out of the "date" unix system command. Here is the code:
  36. {{{
  37. from dateutil.relativedelta import *
  38. from dateutil.easter import *
  39. from dateutil.rrule import *
  40. from dateutil.parser import *
  41. from datetime import *
  42. import commands
  43. import os
  44. now = parse(commands.getoutput("date"))
  45. today = now.date()
  46. year = rrule(YEARLY,bymonth=8,bymonthday=13,byweekday=FR)[0].year
  47. rdelta = relativedelta(easter(year), today)
  48. print "Today is:", today
  49. print "Year with next Aug 13th on a Friday is:", year
  50. print "How far is the Easter of that year:", rdelta
  51. print "And the Easter of that year is:", today+rdelta
  52. }}}
  53. And here's the output:
  54. {{{
  55. Today is: 2003-10-11
  56. Year with next Aug 13th on a Friday is: 2004
  57. How far is the Easter of that year: relativedelta(months=+6)
  58. And the Easter of that year is: 2004-04-11
  59. }}}
  60. {i} Being exactly 6 months ahead was '''really''' a coincidence :)
  61. == Download ==
  62. The following files are available.
  63. * attachment:python-dateutil-1.0.tar.bz2
  64. * attachment:python-dateutil-1.0-1.noarch.rpm
  65. == Author ==
  66. The dateutil module was written by GustavoNiemeyer <gustavo@niemeyer.net>.
  67. == Documentation ==
  68. The following modules are available.
  69. === relativedelta ===
  70. This module offers the '''relativedelta''' type, which is based
  71. on the specification of the excelent work done by M.-A. Lemburg in his
  72. [http://www.egenix.com/files/python/mxDateTime.html mxDateTime]
  73. extension. However, notice that this type '''does not''' implement the
  74. same algorithm as his work. Do not expect it to behave like
  75. {{{mxDateTime}}}'s counterpart.
  76. ==== relativedelta type ====
  77. There's two different ways to build a relativedelta instance. The
  78. first one is passing it two {{{date}}}/{{{datetime}}} instances:
  79. {{{
  80. relativedelta(datetime1, datetime2)
  81. }}}
  82. This will build the relative difference between {{{datetime1}}} and
  83. {{{datetime2}}}, so that the following constraint is always true:
  84. {{{
  85. datetime2+relativedelta(datetime1, datetime2) == datetime1
  86. }}}
  87. Notice that instead of {{{datetime}}} instances, you may use
  88. {{{date}}} instances, or a mix of both.
  89. And the other way is to use any of the following keyword arguments:
  90. year, month, day, hour, minute, second, microsecond::
  91. Absolute information.
  92. years, months, weeks, days, hours, minutes, seconds, microseconds::
  93. Relative information, may be negative.
  94. weekday::
  95. One of the weekday instances ({{{MO}}}, {{{TU}}}, etc). These
  96. instances may receive a parameter {{{n}}}, specifying the {{{n}}}th
  97. weekday, which could be positive or negative (like {{{MO(+2)}}} or
  98. {{{MO(-3)}}}. Not specifying it is the same as specifying {{{+1}}}.
  99. You can also use an integer, where {{{0=MO}}}. Notice that,
  100. for example, if the calculated date is already Monday, using
  101. {{{MO}}} or {{{MO(+1)}}} (which is the same thing in this context),
  102. won't change the day.
  103. leapdays::
  104. Will add given days to the date found, but only if the computed
  105. year is a leap year and the computed date is post 28 of february.
  106. yearday, nlyearday::
  107. Set the yearday or the non-leap year day (jump leap days).
  108. These are converted to {{{day}}}/{{{month}}}/{{{leapdays}}}
  109. information.
  110. ==== Behavior of operations ====
  111. If you're curious about exactly how the relative delta will act
  112. on operations, here is a description of its behavior.
  113. 1. Calculate the absolute year, using the {{{year}}} argument, or the
  114. original datetime year, if the argument is not present.
  115. 1. Add the relative {{{years}}} argument to the absolute year.
  116. 1. Do steps 1 and 2 for {{{month}}}/{{{months}}}.
  117. 1. Calculate the absolute day, using the {{{day}}} argument, or the
  118. original datetime day, if the argument is not present. Then, subtract
  119. from the day until it fits in the year and month found after their
  120. operations.
  121. 1. Add the relative {{{days}}} argument to the absolute day. Notice
  122. that the {{{weeks}}} argument is multiplied by 7 and added to {{{days}}}.
  123. 1. If {{{leapdays}}} is present, the computed year is a leap year, and
  124. the computed month is after february, remove one day from the found date.
  125. 1. Do steps 1 and 2 for {{{hour}}}/{{{hours}}}, {{{minute}}}/{{{minutes}}},
  126. {{{second}}}/{{{seconds}}}, {{{microsecond}}}/{{{microseconds}}}.
  127. 1. If the {{{weekday}}} argument is present, calculate the {{{n}}}th
  128. occurrence of the given weekday.
  129. ==== Examples ====
  130. Let's begin our trip.
  131. {{{
  132. >>> from datetime import *; from dateutil.relativedelta import *
  133. >>> import calendar
  134. }}}
  135. Store some values.
  136. {{{
  137. >>> NOW = datetime.now()
  138. >>> TODAY = date.today()
  139. >>> NOW
  140. datetime.datetime(2003, 9, 17, 20, 54, 47, 282310)
  141. >>> TODAY
  142. datetime.date(2003, 9, 17)
  143. }}}
  144. Next month.
  145. {{{
  146. >>> NOW+relativedelta(months=+1)
  147. datetime.datetime(2003, 10, 17, 20, 54, 47, 282310)
  148. }}}
  149. Next month, plus one week.
  150. {{{
  151. >>> NOW+relativedelta(months=+1, weeks=+1)
  152. datetime.datetime(2003, 10, 24, 20, 54, 47, 282310)
  153. }}}
  154. Next month, plus one week, at 10am.
  155. {{{
  156. >>> TODAY+relativedelta(months=+1, weeks=+1, hour=10)
  157. datetime.datetime(2003, 10, 24, 10, 0)
  158. }}}
  159. Let's try the other way around. Notice that the
  160. hour setting we get in the relativedelta is relative,
  161. since it's a difference, and the weeks parameter
  162. has gone.
  163. {{{
  164. >>> relativedelta(datetime(2003, 10, 24, 10, 0), TODAY)
  165. relativedelta(months=+1, days=+7, hours=+10)
  166. }}}
  167. One month before one year.
  168. {{{
  169. >>> NOW+relativedelta(years=+1, months=-1)
  170. datetime.datetime(2004, 8, 17, 20, 54, 47, 282310)
  171. }}}
  172. How does it handle months with different numbers of days?
  173. Notice that adding one month will never cross the month
  174. boundary.
  175. {{{
  176. >>> date(2003,1,27)+relativedelta(months=+1)
  177. datetime.date(2003, 2, 27)
  178. >>> date(2003,1,31)+relativedelta(months=+1)
  179. datetime.date(2003, 2, 28)
  180. >>> date(2003,1,31)+relativedelta(months=+2)
  181. datetime.date(2003, 3, 31)
  182. }}}
  183. The logic for years is the same, even on leap years.
  184. {{{
  185. >>> date(2000,2,28)+relativedelta(years=+1)
  186. datetime.date(2001, 2, 28)
  187. >>> date(2000,2,29)+relativedelta(years=+1)
  188. datetime.date(2001, 2, 28)
  189. >>> date(1999,2,28)+relativedelta(years=+1)
  190. datetime.date(2000, 2, 28)
  191. >>> date(1999,3,1)+relativedelta(years=+1)
  192. datetime.date(2000, 3, 1)
  193. >>> date(2001,2,28)+relativedelta(years=-1)
  194. datetime.date(2000, 2, 28)
  195. >>> date(2001,3,1)+relativedelta(years=-1)
  196. datetime.date(2000, 3, 1)
  197. }}}
  198. Next friday.
  199. {{{
  200. >>> TODAY+relativedelta(weekday=FR)
  201. datetime.date(2003, 9, 19)
  202. >>> TODAY+relativedelta(weekday=calendar.FRIDAY)
  203. datetime.date(2003, 9, 19)
  204. }}}
  205. Last friday in this month.
  206. {{{
  207. >>> TODAY+relativedelta(day=31, weekday=FR(-1))
  208. datetime.date(2003, 9, 26)
  209. }}}
  210. Next wednesday (it's today!).
  211. {{{
  212. >>> TODAY+relativedelta(weekday=WE(+1))
  213. datetime.date(2003, 9, 17)
  214. }}}
  215. Next wednesday, but not today.
  216. {{{
  217. >>> TODAY+relativedelta(days=+1, weekday=WE(+1))
  218. datetime.date(2003, 9, 24)
  219. }}}
  220. Following
  221. [http://www.cl.cam.ac.uk/~mgk25/iso-time.html ISO year week number notation]
  222. find the first day of the 15th week of 1997.
  223. {{{
  224. >>> datetime(1997,1,1)+relativedelta(day=4, weekday=MO(-1), weeks=+14)
  225. datetime.datetime(1997, 4, 7, 0, 0)
  226. }}}
  227. How long ago has the millennium changed?
  228. {{{
  229. >>> relativedelta(NOW, date(2001,1,1))
  230. relativedelta(years=+2, months=+8, days=+16,
  231. hours=+20, minutes=+54, seconds=+47, microseconds=+282310)
  232. }}}
  233. How old is John?
  234. {{{
  235. >>> johnbirthday = datetime(1978, 4, 5, 12, 0)
  236. >>> relativedelta(NOW, johnbirthday)
  237. relativedelta(years=+25, months=+5, days=+12,
  238. hours=+8, minutes=+54, seconds=+47, microseconds=+282310)
  239. }}}
  240. It works with dates too.
  241. {{{
  242. >>> relativedelta(TODAY, johnbirthday)
  243. relativedelta(years=+25, months=+5, days=+11, hours=+12)
  244. }}}
  245. Obtain today's date using the yearday:
  246. {{{
  247. >>> date(2003, 1, 1)+relativedelta(yearday=260)
  248. datetime.date(2003, 9, 17)
  249. }}}
  250. We can use today's date, since yearday should be absolute
  251. in the given year:
  252. {{{
  253. >>> TODAY+relativedelta(yearday=260)
  254. datetime.date(2003, 9, 17)
  255. }}}
  256. Last year it should be in the same day:
  257. {{{
  258. >>> date(2002, 1, 1)+relativedelta(yearday=260)
  259. datetime.date(2002, 9, 17)
  260. }}}
  261. But not in a leap year:
  262. {{{
  263. >>> date(2000, 1, 1)+relativedelta(yearday=260)
  264. datetime.date(2000, 9, 16)
  265. }}}
  266. We can use the non-leap year day to ignore this:
  267. {{{
  268. >>> date(2000, 1, 1)+relativedelta(nlyearday=260)
  269. datetime.date(2000, 9, 17)
  270. }}}
  271. === rrule ===
  272. The rrule module offers a small, complete, and very fast, implementation
  273. of the recurrence rules documented in the
  274. [ftp://ftp.rfc-editor.org/in-notes/rfc2445.txt iCalendar RFC], including
  275. support for caching of results.
  276. ==== rrule type ====
  277. That's the base of the rrule operation. It accepts all the keywords
  278. defined in the RFC as its constructor parameters (except {{{byday}}},
  279. which was renamed to {{{byweekday}}}) and more. The constructor
  280. prototype is:
  281. {{{
  282. rrule(freq)
  283. }}}
  284. Where {{{freq}}} must be one of {{{YEARLY}}}, {{{MONTHLY}}},
  285. {{{WEEKLY}}}, {{{DAILY}}}, {{{HOURLY}}}, {{{MINUTELY}}},
  286. or {{{SECONDLY}}}.
  287. Additionally, it supports the following keyword arguments:
  288. cache::
  289. If given, it must be a boolean value specifying to enable
  290. or disable caching of results. If you will use the same
  291. {{{rrule}}} instance multiple times, enabling caching will
  292. improve the performance considerably.
  293. dtstart::
  294. The recurrence start. Besides being the base for the
  295. recurrence, missing parameters in the final recurrence
  296. instances will also be extracted from this date. If not
  297. given, {{{datetime.now()}}} will be used instead.
  298. interval::
  299. The interval between each {{{freq}}} iteration. For example,
  300. when using {{{YEARLY}}}, an interval of {{{2}}} means
  301. once every two years, but with {{{HOURLY}}}, it means
  302. once every two hours. The default interval is {{{1}}}.
  303. wkst::
  304. The week start day. Must be one of the {{{MO}}}, {{{TU}}},
  305. {{{WE}}} constants, or an integer, specifying the first day
  306. of the week. This will affect recurrences based on weekly
  307. periods. The default week start is got from
  308. {{{calendar.firstweekday()}}}, and may be modified by
  309. {{{calendar.setfirstweekday()}}}.
  310. count::
  311. How many occurrences will be generated.
  312. until::
  313. If given, this must be a {{{datetime}}} instance, that will
  314. specify the limit of the recurrence. If a recurrence instance
  315. happens to be the same as the {{{datetime}}} instance given
  316. in the {{{until}}} keyword, this will be the last occurrence.
  317. bysetpos::
  318. If given, it must be either an integer, or a sequence of
  319. integers, positive or negative. Each given integer will
  320. specify an occurrence number, corresponding to the nth
  321. occurrence of the rule inside the frequency period. For
  322. example, a {{{bysetpos}}} of {{{-1}}} if combined with a
  323. {{{MONTHLY}}} frequency, and a {{{byweekday}}} of
  324. {{{(MO, TU, WE, TH, FR)}}}, will result in the last work
  325. day of every month.
  326. bymonth::
  327. If given, it must be either an integer, or a sequence of
  328. integers, meaning the months to apply the recurrence to.
  329. bymonthday::
  330. If given, it must be either an integer, or a sequence of
  331. integers, meaning the month days to apply the recurrence to.
  332. byyearday::
  333. If given, it must be either an integer, or a sequence of
  334. integers, meaning the year days to apply the recurrence to.
  335. byweekno::
  336. If given, it must be either an integer, or a sequence of
  337. integers, meaning the week numbers to apply the recurrence
  338. to. Week numbers have the meaning described in ISO8601,
  339. that is, the first week of the year is that containing at
  340. least four days of the new year.
  341. byweekday::
  342. If given, it must be either an integer ({{{0 == MO}}}), a
  343. sequence of integers, one of the weekday constants
  344. ({{{MO}}}, {{{TU}}}, etc), or a sequence of these constants.
  345. When given, these variables will define the weekdays where
  346. the recurrence will be applied. It's also possible to use
  347. an argument {{{n}}} for the weekday instances, which will
  348. mean the {{{n}}}''th'' occurrence of this weekday in the
  349. period. For example, with {{{MONTHLY}}}, or with
  350. {{{YEARLY}}} and {{{BYMONTH}}}, using {{{FR(+1)}}}
  351. in {{{byweekday}}} will specify the first friday of the
  352. month where the recurrence happens. Notice that in the RFC
  353. documentation, this is specified as {{{BYDAY}}}, but was
  354. renamed to avoid the ambiguity of that keyword.
  355. byhour::
  356. If given, it must be either an integer, or a sequence of
  357. integers, meaning the hours to apply the recurrence to.
  358. byminute::
  359. If given, it must be either an integer, or a sequence of
  360. integers, meaning the minutes to apply the recurrence to.
  361. bysecond::
  362. If given, it must be either an integer, or a sequence of
  363. integers, meaning the seconds to apply the recurrence to.
  364. byeaster::
  365. If given, it must be either an integer, or a sequence of
  366. integers, positive or negative. Each integer will define
  367. an offset from the Easter Sunday. Passing the offset
  368. {{{0}}} to {{{byeaster}}} will yield the Easter Sunday
  369. itself. This is an extension to the RFC specification.
  370. ==== rrule methods ====
  371. The following methods are available in {{{rrule}}} instances:
  372. rrule.before(dt, inc=False)::
  373. Returns the last recurrence before the given {{{datetime}}}
  374. instance. The {{{inc}}} keyword defines what happens if
  375. {{{dt}}} '''is''' an occurrence. With {{{inc == True}}},
  376. if {{{dt}}} itself is an occurrence, it will be returned.
  377. rrule.after(dt, inc=False)::
  378. Returns the first recurrence after the given {{{datetime}}}
  379. instance. The {{{inc}}} keyword defines what happens if
  380. {{{dt}}} '''is''' an occurrence. With {{{inc == True}}},
  381. if {{{dt}}} itself is an occurrence, it will be returned.
  382. rrule.between(after, before, inc=False)::
  383. Returns all the occurrences of the rrule between {{{after}}}
  384. and {{{before}}}. The {{{inc}}} keyword defines what happens
  385. if {{{after}}} and/or {{{before}}} are themselves occurrences.
  386. With {{{inc == True}}}, they will be included in the list,
  387. if they are found in the recurrence set.
  388. rrule.count()::
  389. Returns the number of recurrences in this set. It will have
  390. go trough the whole recurrence, if this hasn't been done
  391. before.
  392. Besides these methods, {{{rrule}}} instances also support
  393. the {{{__getitem__()}}} and {{{__contains__()}}} special methods,
  394. meaning that these are valid expressions:
  395. {{{
  396. rr = rrule(...)
  397. if datetime(...) in rr:
  398. ...
  399. print rr[0]
  400. print rr[-1]
  401. print rr[1:2]
  402. print rr[::-2]
  403. }}}
  404. The getitem/slicing mechanism is smart enough to avoid getting the whole
  405. recurrence set, if possible.
  406. ==== Notes ====
  407. * The rrule type has no {{{byday}}} keyword. The equivalent keyword
  408. has been replaced by the {{{byweekday}}} keyword, to remove the
  409. ambiguity present in the original keyword.
  410. * Unlike documented in the RFC, the starting datetime ({{{dtstart}}})
  411. is not the first recurrence instance, unless it does fit in the
  412. specified rules. In a python module context, this behavior makes more
  413. sense than otherwise. Notice that you can easily get the original
  414. behavior by using a rruleset and adding the {{{dtstart}}} as an
  415. {{{rdate}}} recurrence.
  416. * Unlike documented in the RFC, every keyword is valid on every
  417. frequency (the RFC documents that {{{byweekno}}} is only valid
  418. on yearly frequencies, for example).
  419. * In addition to the documented keywords, a {{{byeaster}}} keyword
  420. was introduced, making it easy to compute recurrent events relative
  421. to the Easter Sunday.
  422. ==== rrule examples ====
  423. These examples were converted from the RFC.
  424. Prepare the environment.
  425. {{{
  426. >>> from dateutil.rrule import *
  427. >>> from dateutil.parser import *
  428. >>> from datetime import *
  429. >>> import pprint
  430. >>> import sys
  431. >>> sys.displayhook = pprint.pprint
  432. }}}
  433. Daily, for 10 occurrences.
  434. {{{
  435. >>> list(rrule(DAILY, count=10,
  436. dtstart=parse("19970902T090000")))
  437. [datetime.datetime(1997, 9, 2, 9, 0),
  438. datetime.datetime(1997, 9, 3, 9, 0),
  439. datetime.datetime(1997, 9, 4, 9, 0),
  440. datetime.datetime(1997, 9, 5, 9, 0),
  441. datetime.datetime(1997, 9, 6, 9, 0),
  442. datetime.datetime(1997, 9, 7, 9, 0),
  443. datetime.datetime(1997, 9, 8, 9, 0),
  444. datetime.datetime(1997, 9, 9, 9, 0),
  445. datetime.datetime(1997, 9, 10, 9, 0),
  446. datetime.datetime(1997, 9, 11, 9, 0)]
  447. }}}
  448. Daily until December 24, 1997
  449. {{{
  450. >>> list(rrule(DAILY,
  451. dtstart=parse("19970902T090000"),
  452. until=parse("19971224T000000")))
  453. [datetime.datetime(1997, 9, 2, 9, 0),
  454. datetime.datetime(1997, 9, 3, 9, 0),
  455. datetime.datetime(1997, 9, 4, 9, 0),
  456. (...)
  457. datetime.datetime(1997, 12, 21, 9, 0),
  458. datetime.datetime(1997, 12, 22, 9, 0),
  459. datetime.datetime(1997, 12, 23, 9, 0)]
  460. }}}
  461. Every other day, 5 occurrences.
  462. {{{
  463. >>> list(rrule(DAILY, interval=2, count=5,
  464. dtstart=parse("19970902T090000")))
  465. [datetime.datetime(1997, 9, 2, 9, 0),
  466. datetime.datetime(1997, 9, 4, 9, 0),
  467. datetime.datetime(1997, 9, 6, 9, 0),
  468. datetime.datetime(1997, 9, 8, 9, 0),
  469. datetime.datetime(1997, 9, 10, 9, 0)]
  470. }}}
  471. Every 10 days, 5 occurrences.
  472. {{{
  473. >>> list(rrule(DAILY, interval=10, count=5,
  474. dtstart=parse("19970902T090000")))
  475. [datetime.datetime(1997, 9, 2, 9, 0),
  476. datetime.datetime(1997, 9, 12, 9, 0),
  477. datetime.datetime(1997, 9, 22, 9, 0),
  478. datetime.datetime(1997, 10, 2, 9, 0),
  479. datetime.datetime(1997, 10, 12, 9, 0)]
  480. }}}
  481. Everyday in January, for 3 years.
  482. {{{
  483. >>> list(rrule(YEARLY, bymonth=1, byweekday=range(7),
  484. dtstart=parse("19980101T090000"),
  485. until=parse("20000131T090000")))
  486. [datetime.datetime(1998, 1, 1, 9, 0),
  487. datetime.datetime(1998, 1, 2, 9, 0),
  488. (...)
  489. datetime.datetime(1998, 1, 30, 9, 0),
  490. datetime.datetime(1998, 1, 31, 9, 0),
  491. datetime.datetime(1999, 1, 1, 9, 0),
  492. datetime.datetime(1999, 1, 2, 9, 0),
  493. (...)
  494. datetime.datetime(1999, 1, 30, 9, 0),
  495. datetime.datetime(1999, 1, 31, 9, 0),
  496. datetime.datetime(2000, 1, 1, 9, 0),
  497. datetime.datetime(2000, 1, 2, 9, 0),
  498. (...)
  499. datetime.datetime(2000, 1, 29, 9, 0),
  500. datetime.datetime(2000, 1, 31, 9, 0)]
  501. }}}
  502. Same thing, in another way.
  503. {{{
  504. >>> list(rrule(DAILY, bymonth=1,
  505. dtstart=parse("19980101T090000"),
  506. until=parse("20000131T090000")))
  507. (...)
  508. }}}
  509. Weekly for 10 occurrences.
  510. {{{
  511. >>> list(rrule(WEEKLY, count=10,
  512. dtstart=parse("19970902T090000")))
  513. [datetime.datetime(1997, 9, 2, 9, 0),
  514. datetime.datetime(1997, 9, 9, 9, 0),
  515. datetime.datetime(1997, 9, 16, 9, 0),
  516. datetime.datetime(1997, 9, 23, 9, 0),
  517. datetime.datetime(1997, 9, 30, 9, 0),
  518. datetime.datetime(1997, 10, 7, 9, 0),
  519. datetime.datetime(1997, 10, 14, 9, 0),
  520. datetime.datetime(1997, 10, 21, 9, 0),
  521. datetime.datetime(1997, 10, 28, 9, 0),
  522. datetime.datetime(1997, 11, 4, 9, 0)]
  523. }}}
  524. Every other week, 6 occurrences.
  525. {{{
  526. >>> list(rrule(WEEKLY, interval=2, count=6,
  527. dtstart=parse("19970902T090000")))
  528. [datetime.datetime(1997, 9, 2, 9, 0),
  529. datetime.datetime(1997, 9, 16, 9, 0),
  530. datetime.datetime(1997, 9, 30, 9, 0),
  531. datetime.datetime(1997, 10, 14, 9, 0),
  532. datetime.datetime(1997, 10, 28, 9, 0),
  533. datetime.datetime(1997, 11, 11, 9, 0)]
  534. }}}
  535. Weekly on Tuesday and Thursday for 5 weeks.
  536. {{{
  537. >>> list(rrule(WEEKLY, count=10, wkst=SU, byweekday=(TU,TH),
  538. dtstart=parse("19970902T090000")))
  539. [datetime.datetime(1997, 9, 2, 9, 0),
  540. datetime.datetime(1997, 9, 4, 9, 0),
  541. datetime.datetime(1997, 9, 9, 9, 0),
  542. datetime.datetime(1997, 9, 11, 9, 0),
  543. datetime.datetime(1997, 9, 16, 9, 0),
  544. datetime.datetime(1997, 9, 18, 9, 0),
  545. datetime.datetime(1997, 9, 23, 9, 0),
  546. datetime.datetime(1997, 9, 25, 9, 0),
  547. datetime.datetime(1997, 9, 30, 9, 0),
  548. datetime.datetime(1997, 10, 2, 9, 0)]
  549. }}}
  550. Every other week on Tuesday and Thursday, for 8 occurrences.
  551. {{{
  552. >>> list(rrule(WEEKLY, interval=2, count=8,
  553. wkst=SU, byweekday=(TU,TH),
  554. dtstart=parse("19970902T090000")))
  555. [datetime.datetime(1997, 9, 2, 9, 0),
  556. datetime.datetime(1997, 9, 4, 9, 0),
  557. datetime.datetime(1997, 9, 16, 9, 0),
  558. datetime.datetime(1997, 9, 18, 9, 0),
  559. datetime.datetime(1997, 9, 30, 9, 0),
  560. datetime.datetime(1997, 10, 2, 9, 0),
  561. datetime.datetime(1997, 10, 14, 9, 0),
  562. datetime.datetime(1997, 10, 16, 9, 0)]
  563. }}}
  564. Monthly on the 1st Friday for ten occurrences.
  565. {{{
  566. >>> list(rrule(MONTHLY, count=10, byweekday=FR(1),
  567. dtstart=parse("19970905T090000")))
  568. [datetime.datetime(1997, 9, 5, 9, 0),
  569. datetime.datetime(1997, 10, 3, 9, 0),
  570. datetime.datetime(1997, 11, 7, 9, 0),
  571. datetime.datetime(1997, 12, 5, 9, 0),
  572. datetime.datetime(1998, 1, 2, 9, 0),
  573. datetime.datetime(1998, 2, 6, 9, 0),
  574. datetime.datetime(1998, 3, 6, 9, 0),
  575. datetime.datetime(1998, 4, 3, 9, 0),
  576. datetime.datetime(1998, 5, 1, 9, 0),
  577. datetime.datetime(1998, 6, 5, 9, 0)]
  578. }}}
  579. Every other month on the 1st and last Sunday of the month for 10 occurrences.
  580. {{{
  581. >>> list(rrule(MONTHLY, interval=2, count=10,
  582. byweekday=(SU(1), SU(-1)),
  583. dtstart=parse("19970907T090000")))
  584. [datetime.datetime(1997, 9, 7, 9, 0),
  585. datetime.datetime(1997, 9, 28, 9, 0),
  586. datetime.datetime(1997, 11, 2, 9, 0),
  587. datetime.datetime(1997, 11, 30, 9, 0),
  588. datetime.datetime(1998, 1, 4, 9, 0),
  589. datetime.datetime(1998, 1, 25, 9, 0),
  590. datetime.datetime(1998, 3, 1, 9, 0),
  591. datetime.datetime(1998, 3, 29, 9, 0),
  592. datetime.datetime(1998, 5, 3, 9, 0),
  593. datetime.datetime(1998, 5, 31, 9, 0)]
  594. }}}
  595. Monthly on the second to last Monday of the month for 6 months.
  596. {{{
  597. >>> list(rrule(MONTHLY, count=6, byweekday=MO(-2),
  598. dtstart=parse("19970922T090000")))
  599. [datetime.datetime(1997, 9, 22, 9, 0),
  600. datetime.datetime(1997, 10, 20, 9, 0),
  601. datetime.datetime(1997, 11, 17, 9, 0),
  602. datetime.datetime(1997, 12, 22, 9, 0),
  603. datetime.datetime(1998, 1, 19, 9, 0),
  604. datetime.datetime(1998, 2, 16, 9, 0)]
  605. }}}
  606. Monthly on the third to the last day of the month, for 6 months.
  607. {{{
  608. >>> list(rrule(MONTHLY, count=6, bymonthday=-3,
  609. dtstart=parse("19970928T090000")))
  610. [datetime.datetime(1997, 9, 28, 9, 0),
  611. datetime.datetime(1997, 10, 29, 9, 0),
  612. datetime.datetime(1997, 11, 28, 9, 0),
  613. datetime.datetime(1997, 12, 29, 9, 0),
  614. datetime.datetime(1998, 1, 29, 9, 0),
  615. datetime.datetime(1998, 2, 26, 9, 0)]
  616. }}}
  617. Monthly on the 2nd and 15th of the month for 5 occurrences.
  618. {{{
  619. >>> list(rrule(MONTHLY, count=5, bymonthday=(2,15),
  620. dtstart=parse("19970902T090000")))
  621. [datetime.datetime(1997, 9, 2, 9, 0),
  622. datetime.datetime(1997, 9, 15, 9, 0),
  623. datetime.datetime(1997, 10, 2, 9, 0),
  624. datetime.datetime(1997, 10, 15, 9, 0),
  625. datetime.datetime(1997, 11, 2, 9, 0)]
  626. }}}
  627. Monthly on the first and last day of the month for 3 occurrences.
  628. {{{
  629. >>> list(rrule(MONTHLY, count=5, bymonthday=(-1,1,),
  630. dtstart=parse("1997090
  631. 2T090000")))
  632. [datetime.datetime(1997, 9, 30, 9, 0),
  633. datetime.datetime(1997, 10, 1, 9, 0),
  634. datetime.datetime(1997, 10, 31, 9, 0),
  635. datetime.datetime(1997, 11, 1, 9, 0),
  636. datetime.datetime(1997, 11, 30, 9, 0)]
  637. }}}
  638. Every 18 months on the 10th thru 15th of the month for 10 occurrences.
  639. {{{
  640. >>> list(rrule(MONTHLY, interval=18, count=10,
  641. bymonthday=range(10,16),
  642. dtstart=parse("19970910T090000")))
  643. [datetime.datetime(1997, 9, 10, 9, 0),
  644. datetime.datetime(1997, 9, 11, 9, 0),
  645. datetime.datetime(1997, 9, 12, 9, 0),
  646. datetime.datetime(1997, 9, 13, 9, 0),
  647. datetime.datetime(1997, 9, 14, 9, 0),
  648. datetime.datetime(1997, 9, 15, 9, 0),
  649. datetime.datetime(1999, 3, 10, 9, 0),
  650. datetime.datetime(1999, 3, 11, 9, 0),
  651. datetime.datetime(1999, 3, 12, 9, 0),
  652. datetime.datetime(1999, 3, 13, 9, 0)]
  653. }}}
  654. Every Tuesday, every other month, 6 occurences.
  655. {{{
  656. >>> list(rrule(MONTHLY, interval=2, count=6, byweekday=TU,
  657. dtstart=parse("19970902T090000")))
  658. [datetime.datetime(1997, 9, 2, 9, 0),
  659. datetime.datetime(1997, 9, 9, 9, 0),
  660. datetime.datetime(1997, 9, 16, 9, 0),
  661. datetime.datetime(1997, 9, 23, 9, 0),
  662. datetime.datetime(1997, 9, 30, 9, 0),
  663. datetime.datetime(1997, 11, 4, 9, 0)]
  664. }}}
  665. Yearly in June and July for 10 occurrences.
  666. {{{
  667. >>> list(rrule(YEARLY, count=4, bymonth=(6,7),
  668. dtstart=parse("19970610T0900
  669. 00")))
  670. [datetime.datetime(1997, 6, 10, 9, 0),
  671. datetime.datetime(1997, 7, 10, 9, 0),
  672. datetime.datetime(1998, 6, 10, 9, 0),
  673. datetime.datetime(1998, 7, 10, 9, 0)]
  674. }}}
  675. Every 3rd year on the 1st, 100th and 200th day for 4 occurrences.
  676. {{{
  677. >>> list(rrule(YEARLY, count=4, interval=3, byyearday=(1,100,200),
  678. dtstart=parse("19970101T090000")))
  679. [datetime.datetime(1997, 1, 1, 9, 0),
  680. datetime.datetime(1997, 4, 10, 9, 0),
  681. datetime.datetime(1997, 7, 19, 9, 0),
  682. datetime.datetime(2000, 1, 1, 9, 0)]
  683. }}}
  684. Every 20th Monday of the year, 3 occurrences.
  685. {{{
  686. >>> list(rrule(YEARLY, count=3, byweekday=MO(20),
  687. dtstart=parse("19970519T090000")))
  688. [datetime.datetime(1997, 5, 19, 9, 0),
  689. datetime.datetime(1998, 5, 18, 9, 0),
  690. datetime.datetime(1999, 5, 17, 9, 0)]
  691. }}}
  692. Monday of week number 20 (where the default start of the week is Monday),
  693. 3 occurrences.
  694. {{{
  695. >>> list(rrule(YEARLY, count=3, byweekno=20, byweekday=MO,
  696. dtstart=parse("19970512T090000")))
  697. [datetime.datetime(1997, 5, 12, 9, 0),
  698. datetime.datetime(1998, 5, 11, 9, 0),
  699. datetime.datetime(1999, 5, 17, 9, 0)]
  700. }}}
  701. The week number 1 may be in the last year.
  702. {{{
  703. >>> list(rrule(WEEKLY, count=3, byweekno=1, byweekday=MO,
  704. dtstart=parse("19970902T090000")))
  705. [datetime.datetime(1997, 12, 29, 9, 0),
  706. datetime.datetime(1999, 1, 4, 9, 0),
  707. datetime.datetime(2000, 1, 3, 9, 0)]
  708. }}}
  709. And the week numbers greater than 51 may be in the next year.
  710. {{{
  711. >>> list(rrule(WEEKLY, count=3, byweekno=52, byweekday=SU,
  712. dtstart=parse("19970902T090000")))
  713. [datetime.datetime(1997, 12, 28, 9, 0),
  714. datetime.datetime(1998, 12, 27, 9, 0),
  715. datetime.datetime(2000, 1, 2, 9, 0)]
  716. }}}
  717. Only some years have week number 53:
  718. {{{
  719. >>> list(rrule(WEEKLY, count=3, byweekno=53, byweekday=MO,
  720. dtstart=parse("19970902T090000")))
  721. [datetime.datetime(1998, 12, 28, 9, 0),
  722. datetime.datetime(2004, 12, 27, 9, 0),
  723. datetime.datetime(2009, 12, 28, 9, 0)]
  724. }}}
  725. Every Friday the 13th, 4 occurrences.
  726. {{{
  727. >>> list(rrule(YEARLY, count=4, byweekday=FR, bymonthday=13,
  728. dtstart=parse("19970902T090000")))
  729. [datetime.datetime(1998, 2, 13, 9, 0),
  730. datetime.datetime(1998, 3, 13, 9, 0),
  731. datetime.datetime(1998, 11, 13, 9, 0),
  732. datetime.datetime(1999, 8, 13, 9, 0)]
  733. }}}
  734. Every four years, the first Tuesday after a Monday in November,
  735. 3 occurrences (U.S. Presidential Election day):
  736. {{{
  737. >>> list(rrule(YEARLY, interval=4, count=3, bymonth=11,
  738. byweekday=TU, bymonthday=(2,3,4,5,6,7,8),
  739. dtstart=parse("19961105T090000")))
  740. [datetime.datetime(1996, 11, 5, 9, 0),
  741. datetime.datetime(2000, 11, 7, 9, 0),
  742. datetime.datetime(2004, 11, 2, 9, 0)]
  743. }}}
  744. The 3rd instance into the month of one of Tuesday, Wednesday or
  745. Thursday, for the next 3 months:
  746. {{{
  747. >>> list(rrule(MONTHLY, count=3, byweekday=(TU,WE,TH),
  748. bysetpos=3, dtstart=parse("19970904T090000")))
  749. [datetime.datetime(1997, 9, 4, 9, 0),
  750. datetime.datetime(1997, 10, 7, 9, 0),
  751. datetime.datetime(1997, 11, 6, 9, 0)]
  752. }}}
  753. The 2nd to last weekday of the month, 3 occurrences.
  754. {{{
  755. >>> list(rrule(MONTHLY, count=3, byweekday=(MO,TU,WE,TH,FR),
  756. bysetpos=-2, dtstart=parse("19970929T090000")))
  757. [datetime.datetime(1997, 9, 29, 9, 0),
  758. datetime.datetime(1997, 10, 30, 9, 0),
  759. datetime.datetime(1997, 11, 27, 9, 0)]
  760. }}}
  761. Every 3 hours from 9:00 AM to 5:00 PM on a specific day.
  762. {{{
  763. >>> list(rrule(HOURLY, interval=3,
  764. dtstart=parse("19970902T090000"),
  765. until=parse("19970902T170000")))
  766. [datetime.datetime(1997, 9, 2, 9, 0),
  767. datetime.datetime(1997, 9, 2, 12, 0),
  768. datetime.datetime(1997, 9, 2, 15, 0)]
  769. }}}
  770. Every 15 minutes for 6 occurrences.
  771. {{{
  772. >>> list(rrule(MINUTELY, interval=15, count=6,
  773. dtstart=parse("19970902T090000")))
  774. [datetime.datetime(1997, 9, 2, 9, 0),
  775. datetime.datetime(1997, 9, 2, 9, 15),
  776. datetime.datetime(1997, 9, 2, 9, 30),
  777. datetime.datetime(1997, 9, 2, 9, 45),
  778. datetime.datetime(1997, 9, 2, 10, 0),
  779. datetime.datetime(1997, 9, 2, 10, 15)]
  780. }}}
  781. Every hour and a half for 4 occurrences.
  782. {{{
  783. >>> list(rrule(MINUTELY, interval=90, count=4,
  784. dtstart=parse("19970902T090000")))
  785. [datetime.datetime(1997, 9, 2, 9, 0),
  786. datetime.datetime(1997, 9, 2, 10, 30),
  787. datetime.datetime(1997, 9, 2, 12, 0),
  788. datetime.datetime(1997, 9, 2, 13, 30)]
  789. }}}
  790. Every 20 minutes from 9:00 AM to 4:40 PM for two days.
  791. {{{
  792. >>> list(rrule(MINUTELY, interval=20, count=48,
  793. byhour=range(9,17), byminute=(0,20,40),
  794. dtstart=parse("19970902T090000")))
  795. [datetime.datetime(1997, 9, 2, 9, 0),
  796. datetime.datetime(1997, 9, 2, 9, 20),
  797. (...)
  798. datetime.datetime(1997, 9, 2, 16, 20),
  799. datetime.datetime(1997, 9, 2, 16, 40),
  800. datetime.datetime(1997, 9, 3, 9, 0),
  801. datetime.datetime(1997, 9, 3, 9, 20),
  802. (...)
  803. datetime.datetime(1997, 9, 3, 16, 20),
  804. datetime.datetime(1997, 9, 3, 16, 40)]
  805. }}}
  806. An example where the days generated makes a difference because of {{{wkst}}}.
  807. {{{
  808. >>> list(rrule(WEEKLY, interval=2, count=4,
  809. byweekday=(TU,SU), wkst=MO,
  810. dtstart=parse("19970805T090000")))
  811. [datetime.datetime(1997, 8, 5, 9, 0),
  812. datetime.datetime(1997, 8, 10, 9, 0),
  813. datetime.datetime(1997, 8, 19, 9, 0),
  814. datetime.datetime(1997, 8, 24, 9, 0)]
  815. >>> list(rrule(WEEKLY, interval=2, count=4,
  816. byweekday=(TU,SU), wkst=SU,
  817. dtstart=parse("19970805T090000")))
  818. [datetime.datetime(1997, 8, 5, 9, 0),
  819. datetime.datetime(1997, 8, 17, 9, 0),
  820. datetime.datetime(1997, 8, 19, 9, 0),
  821. datetime.datetime(1997, 8, 31, 9, 0)]
  822. }}}
  823. ==== rruleset type ====
  824. The {{{rruleset}}} type allows more complex recurrence setups, mixing
  825. multiple rules, dates, exclusion rules, and exclusion dates.
  826. The type constructor takes the following keyword arguments:
  827. cache::
  828. If True, caching of results will be enabled, improving performance
  829. of multiple queries considerably.
  830. ==== rruleset methods ====
  831. The following methods are available:
  832. rruleset.rrule(rrule)::
  833. Include the given {{{rrule}}} instance in the recurrence set
  834. generation.
  835. rruleset.rdate(dt)::
  836. Include the given {{{datetime}}} instance in the recurrence
  837. set generation.
  838. rruleset.exrule(rrule)::
  839. Include the given {{{rrule}}} instance in the recurrence set
  840. exclusion list. Dates which are part of the given recurrence
  841. rules will not be generated, even if some inclusive {{{rrule}}}
  842. or {{{rdate}}} matches them.
  843. rruleset.exdate(dt)::
  844. Include the given {{{datetime}}} instance in the recurrence set
  845. exclusion list. Dates included that way will not be generated,
  846. even if some inclusive {{{rrule}}} or {{{rdate}}} matches them.
  847. rruleset.before(dt, inc=False)::
  848. Returns the last recurrence before the given {{{datetime}}}
  849. instance. The {{{inc}}} keyword defines what happens if
  850. {{{dt}}} '''is''' an occurrence. With {{{inc == True}}},
  851. if {{{dt}}} itself is an occurrence, it will be returned.
  852. rruleset.after(dt, inc=False)::
  853. Returns the first recurrence after the given {{{datetime}}}
  854. instance. The {{{inc}}} keyword defines what happens if
  855. {{{dt}}} '''is''' an occurrence. With {{{inc == True}}},
  856. if {{{dt}}} itself is an occurrence, it will be returned.
  857. rruleset.between(after, before, inc=False)::
  858. Returns all the occurrences of the rrule between {{{after}}}
  859. and {{{before}}}. The {{{inc}}} keyword defines what happens
  860. if {{{after}}} and/or {{{before}}} are themselves occurrences.
  861. With {{{inc == True}}}, they will be included in the list,
  862. if they are found in the recurrence set.
  863. rruleset.count()::
  864. Returns the number of recurrences in this set. It will have
  865. go trough the whole recurrence, if this hasn't been done
  866. before.
  867. Besides these methods, {{{rruleset}}} instances also support
  868. the {{{__getitem__()}}} and {{{__contains__()}}} special methods,
  869. meaning that these are valid expressions:
  870. {{{
  871. set = rruleset(...)
  872. if datetime(...) in set:
  873. ...
  874. print set[0]
  875. print set[-1]
  876. print set[1:2]
  877. print set[::-2]
  878. }}}
  879. The getitem/slicing mechanism is smart enough to avoid getting the whole
  880. recurrence set, if possible.
  881. ==== rruleset examples ====
  882. Daily, for 7 days, jumping Saturday and Sunday occurrences.
  883. {{{
  884. >>> set = rruleset()
  885. >>> set.rrule(rrule(DAILY, count=7,
  886. dtstart=parse("19970902T090000")))
  887. >>> set.exrule(rrule(YEARLY, byweekday=(SA,SU),
  888. dtstart=parse("19970902T090000")))
  889. >>> list(set)
  890. [datetime.datetime(1997, 9, 2, 9, 0),
  891. datetime.datetime(1997, 9, 3, 9, 0),
  892. datetime.datetime(1997, 9, 4, 9, 0),
  893. datetime.datetime(1997, 9, 5, 9, 0),
  894. datetime.datetime(1997, 9, 8, 9, 0)]
  895. }}}
  896. Weekly, for 4 weeks, plus one time on day 7, and not on day 16.
  897. {{{
  898. >>> set = rruleset()
  899. >>> set.rrule(rrule(WEEKLY, count=4,
  900. dtstart=parse("19970902T090000")))
  901. >>> set.rdate(datetime.datetime(1997, 9, 7, 9, 0))
  902. >>> set.exdate(datetime.datetime(1997, 9, 16, 9, 0))
  903. >>> list(set)
  904. [datetime.datetime(1997, 9, 2, 9, 0),
  905. datetime.datetime(1997, 9, 7, 9, 0),
  906. datetime.datetime(1997, 9, 9, 9, 0),
  907. datetime.datetime(1997, 9, 23, 9, 0)]
  908. }}}
  909. ==== rrulestr() function ====
  910. The {{{rrulestr()}}} function is a parser for ''RFC-like'' syntaxes.
  911. The function prototype is:
  912. {{{
  913. rrulestr(str)
  914. }}}
  915. The string passed as parameter may be a multiple line string, a
  916. single line string, or just the {{{RRULE}}} property value.
  917. Additionally, it accepts the following keyword arguments:
  918. cache::
  919. If {{{True}}}, the {{{rruleset}}} or {{{rrule}}} created instance
  920. will cache its results. Default is not to cache.
  921. dtstart::
  922. If given, it must be a {{{datetime}}} instance that will be used
  923. when no {{{DTSTART}}} property is found in the parsed string. If
  924. it is not given, and the property is not found, {{{datetime.now()}}}
  925. will be used instead.
  926. unfold::
  927. If set to {{{True}}}, lines will be unfolded following the RFC
  928. specification. It defaults to {{{False}}}, meaning that spaces
  929. before every line will be stripped.
  930. forceset::
  931. If set to {{{True}}} a {{{rruleset}}} instance will be returned,
  932. even if only a single rule is found. The default is to return an
  933. {{{rrule}}} if possible, and an {{{rruleset}}} if necessary.
  934. compatible::
  935. If set to {{{True}}}, the parser will operate in RFC-compatible
  936. mode. Right now it means that {{{unfold}}} will be turned on,
  937. and if a {{{DTSTART}}} is found, it will be considered the first
  938. recurrence instance, as documented in the RFC.
  939. ignoretz::
  940. If set to {{{True}}}, the date parser will ignore timezone
  941. information available in the {{{DTSTART}}} property, or the
  942. {{{UNTIL}}} attribute.
  943. tzinfos::
  944. If set, it will be passed to the datetime string parser to
  945. resolve unknown timezone settings. For more information about
  946. what could be used here, check the parser documentation.
  947. ==== rrulestr() examples ====
  948. Every 10 days, 5 occurrences.
  949. {{{
  950. >>> list(rrulestr("""
  951. ... DTSTART:19970902T090000
  952. ... RRULE:FREQ=DAILY;INTERVAL=10;COUNT=5
  953. ... """))
  954. [datetime.datetime(1997, 9, 2, 9, 0),
  955. datetime.datetime(1997, 9, 12, 9, 0),
  956. datetime.datetime(1997, 9, 22, 9, 0),
  957. datetime.datetime(1997, 10, 2, 9, 0),
  958. datetime.datetime(1997, 10, 12, 9, 0)]
  959. }}}
  960. Same thing, but passing only the {{{RRULE}}} value.
  961. {{{
  962. >>> list(rrulestr("FREQ=DAILY;INTERVAL=10;COUNT=5",
  963. dtstart=parse("19970902T090000")))
  964. [datetime.datetime(1997, 9, 2, 9, 0),
  965. datetime.datetime(1997, 9, 12, 9, 0),
  966. datetime.datetime(1997, 9, 22, 9, 0),
  967. datetime.datetime(1997, 10, 2, 9, 0),
  968. datetime.datetime(1997, 10, 12, 9, 0)]
  969. }}}
  970. Notice that when using a single rule, it returns an
  971. {{{rrule}}} instance, unless {{{forceset}}} was used.
  972. {{{
  973. >>> rrulestr("FREQ=DAILY;INTERVAL=10;COUNT=5")
  974. <dateutil.rrule.rrule instance at 0x30269f08>
  975. >>> rrulestr("""
  976. ... DTSTART:19970902T090000
  977. ... RRULE:FREQ=DAILY;INTERVAL=10;COUNT=5
  978. ... """)
  979. <dateutil.rrule.rrule instance at 0x302699e0>
  980. >>> rrulestr("FREQ=DAILY;INTERVAL=10;COUNT=5", forceset=True)
  981. <dateutil.rrule.rruleset instance at 0x30269f08>
  982. }}}
  983. But when an {{{rruleset}}} is needed, it is automatically used.
  984. {{{
  985. >>> rrulestr("""
  986. ... DTSTART:19970902T090000
  987. ... RRULE:FREQ=DAILY;INTERVAL=10;COUNT=5
  988. ... RRULE:FREQ=DAILY;INTERVAL=5;COUNT=3
  989. ... """)
  990. <dateutil.rrule.rruleset instance at 0x302699e0>
  991. }}}
  992. === parser ===
  993. This module offers a generic date/time string parser which is
  994. able to parse most known formats to represent a date and/or
  995. time.
  996. ==== parse() function ====
  997. That's probably the only function you'll need from this module.
  998. It offers you an interface to access the parser functionality and
  999. extract a {{{datetime}}} type out of a string.
  1000. The prototype of this function is:
  1001. {{{
  1002. parse(timestr)
  1003. }}}
  1004. Additionally, the following keyword arguments are available:
  1005. default::
  1006. If given, this must be a {{{datetime}}} instance. Any fields
  1007. missing in the parsed date will be copied from this instance.
  1008. The default value is the current date, at 00:00:00am.
  1009. ignoretz::
  1010. If this is true, even if a timezone is found in the string,
  1011. the parser will not use it.
  1012. tzinfos::
  1013. Using this keyword argument you may provide custom timezones
  1014. to the parser. If given, it must be either a dictionary with
  1015. the timezone abbreviation as key, or a function accepting a
  1016. timezone abbreviation and offset as argument. The dictionary
  1017. values and the function return must be a timezone offset
  1018. in seconds, a tzinfo subclass, or a string defining the
  1019. timezone (in the TZ environment variable format).
  1020. dayfirst::
  1021. This option allow one to change the precedence in which
  1022. days are parsed in date strings. The default is given in the
  1023. parserinfo instance (the default parserinfo has it set to
  1024. False). If {{{dayfirst}}} is False, the {{{MM-DD-YYYY}}}
  1025. format will have precedence over {{{DD-MM-YYYY}}} in an
  1026. ambiguous date.
  1027. yearfirst::
  1028. This option allow one to change the precedence in which
  1029. years are parsed in date strings. The default is given in
  1030. the parserinfo instance (the default parserinfo has it set
  1031. to False). If {{{yearfirst}}} is false, the {{{MM-DD-YY}}}
  1032. format will have precedence over {{{YY-MM-DD}}} in an
  1033. ambiguous date.
  1034. fuzzy::
  1035. If {{{fuzzy}}} is set to True, unknown tokens in the string
  1036. will be ignored.
  1037. parserinfo::
  1038. This parameter allows one to change how the string is parsed,
  1039. by using a different parserinfo class instance. Using it you
  1040. may, for example, intenationalize the parser strings, or make
  1041. it ignore additional words.
  1042. ==== Format precedence ====
  1043. Whenever an ambiguous date is found, the {{{dayfirst}}} and
  1044. {{{yearfirst}}} parameters will control how the information
  1045. is processed. Here is the precedence in each case:
  1046. If {{{dayfirst}}} is {{{False}}} and {{{yearfirst}}} is {{{False}}},
  1047. (default, if no parameter is given):
  1048. * {{{MM-DD-YY}}}
  1049. * {{{DD-MM-YY}}}
  1050. * {{{YY-MM-DD}}}
  1051. If {{{dayfirst}}} is {{{True}}} and {{{yearfirst}}} is {{{False}}}:
  1052. * {{{DD-MM-YY}}}
  1053. * {{{MM-DD-YY}}}
  1054. * {{{YY-MM-DD}}}
  1055. If {{{dayfirst}}} is {{{False}}} and {{{yearfirst}}} is {{{True}}}:
  1056. * {{{YY-MM-DD}}}
  1057. * {{{MM-DD-YY}}}
  1058. * {{{DD-MM-YY}}}
  1059. If {{{dayfirst}}} is {{{True}}} and {{{yearfirst}}} is {{{True}}}:
  1060. * {{{YY-MM-DD}}}
  1061. * {{{DD-MM-YY}}}
  1062. * {{{MM-DD-YY}}}
  1063. ==== Converting two digit years ====
  1064. When a two digit year is found, it is processed considering
  1065. the current year, so that the computed year is never more
  1066. than 49 years after the current year, nor 50 years before the
  1067. current year. In other words, if we are in year 2003, and the
  1068. year 30 is found, it will be considered as 2030, but if the
  1069. year 60 is found, it will be considered 1960.
  1070. ==== Examples ====
  1071. The following code will prepare the environment:
  1072. {{{
  1073. >>> from dateutil.parser import *
  1074. >>> from dateutil.tz import *
  1075. >>> from datetime import *
  1076. >>> TZOFFSETS = {"BRST": -10800}
  1077. >>> BRSTTZ = tzoffset(-10800, "BRST")
  1078. >>> DEFAULT = datetime(2003, 9, 25)
  1079. }}}
  1080. Some simple examples based on the {{{date}}} command, using the
  1081. {{{TZOFFSET}}} dictionary to provide the BRST timezone offset.
  1082. {{{
  1083. >>> parse("Thu Sep 25 10:36:28 BRST 2003", tzinfos=TZOFFSETS)
  1084. datetime.datetime(2003, 9, 25, 10, 36, 28,
  1085. tzinfo=tzoffset('BRST', -10800))
  1086. >>> parse("2003 10:36:28 BRST 25 Sep Thu", tzinfos=TZOFFSETS)
  1087. datetime.datetime(2003, 9, 25, 10, 36, 28,
  1088. tzinfo=tzoffset('BRST', -10800))
  1089. }}}
  1090. Notice that since BRST is my local timezone, parsing it without
  1091. further timezone settings will yield a {{{tzlocal}}} timezone.
  1092. {{{
  1093. >>> parse("Thu Sep 25 10:36:28 BRST 2003")
  1094. datetime.datetime(2003, 9, 25, 10, 36, 28, tzinfo=tzlocal())
  1095. }}}
  1096. We can also ask to ignore the timezone explicitly:
  1097. {{{
  1098. >>> parse("Thu Sep 25 10:36:28 BRST 2003", ignoretz=True)
  1099. datetime.datetime(2003, 9, 25, 10, 36, 28)
  1100. }}}
  1101. That's the same as processing a string without timezone:
  1102. {{{
  1103. >>> parse("Thu Sep 25 10:36:28 2003")
  1104. datetime.datetime(2003, 9, 25, 10, 36, 28)
  1105. }}}
  1106. Without the year, but passing our {{{DEFAULT}}} datetime to return
  1107. the same year, no mattering what year we currently are in:
  1108. {{{
  1109. >>> parse("Thu Sep 25 10:36:28", default=DEFAULT)
  1110. datetime.datetime(2003, 9, 25, 10, 36, 28)
  1111. }}}
  1112. Strip it further:
  1113. {{{
  1114. >>> parse("Thu Sep 10:36:28", default=DEFAULT)
  1115. datetime.datetime(2003, 9, 25, 10, 36, 28)
  1116. >>> parse("Thu 10:36:28", default=DEFAULT)
  1117. datetime.datetime(2003, 9, 25, 10, 36, 28)
  1118. >>> parse("Thu 10:36", default=DEFAULT)
  1119. datetime.datetime(2003, 9, 25, 10, 36)
  1120. >>> parse("10:36", default=DEFAULT)
  1121. datetime.datetime(2003, 9, 25, 10, 36)
  1122. >>>
  1123. }}}
  1124. Strip in a different way:
  1125. {{{
  1126. >>> parse("Thu Sep 25 2003")
  1127. datetime.datetime(2003, 9, 25, 0, 0)
  1128. >>> parse("Sep 25 2003")
  1129. datetime.datetime(2003, 9, 25, 0, 0)
  1130. >>> parse("Sep 2003", default=DEFAULT)
  1131. datetime.datetime(2003, 9, 25, 0, 0)
  1132. >>> parse("Sep", default=DEFAULT)
  1133. datetime.datetime(2003, 9, 25, 0, 0)
  1134. >>> parse("2003", default=DEFAULT)
  1135. datetime.datetime(2003, 9, 25, 0, 0)
  1136. }}}
  1137. Another format, based on {{{date -R}}} (RFC822):
  1138. {{{
  1139. >>> parse("Thu, 25 Sep 2003 10:49:41 -0300")
  1140. datetime.datetime(2003, 9, 25, 10, 49, 41,
  1141. tzinfo=tzoffset(None, -10800))
  1142. }}}
  1143. ISO format:
  1144. {{{
  1145. >>> parse("2003-09-25T10:49:41.5-03:00")
  1146. datetime.datetime(2003, 9, 25, 10, 49, 41, 500000,
  1147. tzinfo=tzoffset(None, -10800))
  1148. }}}
  1149. Some variations:
  1150. {{{
  1151. >>> parse("2003-09-25T10:49:41")
  1152. datetime.datetime(2003, 9, 25, 10, 49, 41)
  1153. >>> parse("2003-09-25T10:49")
  1154. datetime.datetime(2003, 9, 25, 10, 49)
  1155. >>> parse("2003-09-25T10")
  1156. datetime.datetime(2003, 9, 25, 10, 0)
  1157. >>> parse("2003-09-25")
  1158. datetime.datetime(2003, 9, 25, 0, 0)
  1159. }}}
  1160. ISO format, without separators:
  1161. {{{
  1162. >>> parse("20030925T104941.5-0300")
  1163. datetime.datetime(2003, 9, 25, 10, 49, 41, 500000,
  1164. tzinfo=tzinfo=tzoffset(None, -10800))
  1165. >>> parse("20030925T104941-0300")
  1166. datetime.datetime(2003, 9, 25, 10, 49, 41,
  1167. tzinfo=tzoffset(None, -10800))
  1168. >>> parse("20030925T104941")
  1169. datetime.datetime(2003, 9, 25, 10, 49, 41)
  1170. >>> parse("20030925T1049")
  1171. datetime.datetime(2003, 9, 25, 10, 49)
  1172. >>> parse("20030925T10")
  1173. datetime.datetime(2003, 9, 25, 10, 0)
  1174. >>> parse("20030925")
  1175. datetime.datetime(2003, 9, 25, 0, 0)
  1176. }}}
  1177. Everything together.
  1178. {{{
  1179. >>> parse("199709020900")
  1180. datetime.datetime(1997, 9, 2, 9, 0)
  1181. >>> parse("19970902090059")
  1182. datetime.datetime(1997, 9, 2, 9, 0, 59)
  1183. }}}
  1184. Different date orderings:
  1185. {{{
  1186. >>> parse("2003-09-25")
  1187. datetime.datetime(2003, 9, 25, 0, 0)
  1188. >>> parse("2003-Sep-25")
  1189. datetime.datetime(2003, 9, 25, 0, 0)
  1190. >>> parse("25-Sep-2003")
  1191. datetime.datetime(2003, 9, 25, 0, 0)
  1192. >>> parse("Sep-25-2003")
  1193. datetime.datetime(2003, 9, 25, 0, 0)
  1194. >>> parse("09-25-2003")
  1195. datetime.datetime(2003, 9, 25, 0, 0)
  1196. >>> parse("25-09-2003")
  1197. datetime.datetime(2003, 9, 25, 0, 0)
  1198. }}}
  1199. Check some ambiguous dates:
  1200. {{{
  1201. >>> parse("10-09-2003")
  1202. datetime.datetime(2003, 10, 9, 0, 0)
  1203. >>> parse("10-09-2003", dayfirst=True)
  1204. datetime.datetime(2003, 9, 10, 0, 0)
  1205. >>> parse("10-09-03")
  1206. datetime.datetime(2003, 10, 9, 0, 0)
  1207. >>> parse("10-09-03", yearfirst=True)
  1208. datetime.datetime(2010, 9, 3, 0, 0)
  1209. }}}
  1210. Other date separators are allowed:
  1211. {{{
  1212. >>> parse("2003.Sep.25")
  1213. datetime.datetime(2003, 9, 25, 0, 0)
  1214. >>> parse("2003/09/25")
  1215. datetime.datetime(2003, 9, 25, 0, 0)
  1216. }}}
  1217. Even with spaces:
  1218. {{{
  1219. >>> parse("2003 Sep 25")
  1220. datetime.datetime(2003, 9, 25, 0, 0)
  1221. >>> parse("2003 09 25")
  1222. datetime.datetime(2003, 9, 25, 0, 0)
  1223. }}}
  1224. Hours with letters work:
  1225. {{{
  1226. >>> parse("10h36m28.5s", default=DEFAULT)
  1227. datetime.datetime(2003, 9, 25, 10, 36, 28, 500000)
  1228. >>> parse("01s02h03m", default=DEFAULT)
  1229. datetime.datetime(2003, 9, 25, 2, 3, 1)
  1230. >>> parse("01h02m03", default=DEFAULT)
  1231. datetime.datetime(2003, 9, 3, 1, 2)
  1232. >>> parse("01h02", default=DEFAULT)
  1233. datetime.datetime(2003, 9, 2, 1, 0)
  1234. >>> parse("01h02s", default=DEFAULT)
  1235. datetime.datetime(2003, 9, 25, 1, 0, 2)
  1236. }}}
  1237. With AM/PM:
  1238. {{{
  1239. >>> parse("10h am", default=DEFAULT)
  1240. datetime.datetime(2003, 9, 25, 10, 0)
  1241. >>> parse("10pm", default=DEFAULT)
  1242. datetime.datetime(2003, 9, 25, 22, 0)
  1243. >>> parse("12:00am", default=DEFAULT)
  1244. datetime.datetime(2003, 9, 25, 0, 0)
  1245. >>> parse("12pm", default=DEFAULT)
  1246. datetime.datetime(2003, 9, 25, 12, 0)
  1247. }}}
  1248. Some special treating for ''pertain'' relations:
  1249. {{{
  1250. >>> parse("Sep 03", default=DEFAULT)
  1251. datetime.datetime(2003, 9, 3, 0, 0)
  1252. >>> parse("Sep of 03", default=DEFAULT)
  1253. datetime.datetime(2003, 9, 25, 0, 0)
  1254. }}}
  1255. Fuzzy parsing:
  1256. {{{
  1257. >>> s = "Today is 25 of September of 2003, exactly " \
  1258. ... "at 10:49:41 with timezone -03:00."
  1259. >>> parse(s, fuzzy=True)
  1260. datetime.datetime(2003, 9, 25, 10, 49, 41,
  1261. tzinfo=tzoffset(None, -10800))
  1262. }}}
  1263. Other random formats:
  1264. {{{
  1265. >>> parse("Wed, July 10, '96")
  1266. datetime.datetime(1996, 7, 10, 0, 0)
  1267. >>> parse("1996.07.10 AD at 15:08:56 PDT", ignoretz=True)
  1268. datetime.datetime(1996, 7, 10, 15, 8, 56)
  1269. >>> parse("Tuesday, April 12, 1952 AD 3:30:42pm PST", ignoretz=True)
  1270. datetime.datetime(1952, 4, 12, 15, 30, 42)
  1271. >>> parse("November 5, 1994, 8:15:30 am EST", ignoretz=True)
  1272. datetime.datetime(1994, 11, 5, 8, 15, 30)
  1273. >>> parse("3rd of May 2001")
  1274. datetime.datetime(2001, 5, 3, 0, 0)
  1275. >>> parse("5:50 A.M. on June 13, 1990")
  1276. datetime.datetime(1990, 6, 13, 5, 50)
  1277. }}}
  1278. === easter ===
  1279. This module offers a generic easter computing method for
  1280. any given year, using Western, Orthodox or Julian algorithms.
  1281. ==== easter() function ====
  1282. This method was ported from the work done by
  1283. [http://users.chariot.net.au/~gmarts/eastalg.htm GM Arts],
  1284. on top of the algorithm by
  1285. [http://www.tondering.dk/claus/calendar.html Claus Tondering],
  1286. which was based in part on the algorithm of Ouding (1940),
  1287. as quoted in "Explanatory Supplement to the Astronomical
  1288. Almanac", P. Kenneth Seidelmann, editor.
  1289. This algorithm implements three different easter
  1290. calculation methods:
  1291. 1. Original calculation in Julian calendar, valid in
  1292. dates after 326 AD
  1293. 1. Original method, with date converted to Gregorian
  1294. calendar, valid in years 1583 to 4099
  1295. 1. Revised method, in Gregorian calendar, valid in
  1296. years 1583 to 4099 as well
  1297. These methods are represented by the constants:
  1298. {{{
  1299. EASTER_JULIAN = 1
  1300. EASTER_ORTHODOX = 2
  1301. EASTER_WESTERN = 3
  1302. }}}
  1303. The default method is method 3.
  1304. === tz ===
  1305. This module offers timezone implementations subclassing
  1306. the abstract {{{datetime.tzinfo}}} type. There are
  1307. classes to handle [http://www.twinsun.com/tz/tz-link.htm tzfile]
  1308. format files (usually are in /etc/localtime,
  1309. /usr/share/zoneinfo, etc), TZ environment string (in all
  1310. known formats), given ranges (with help from relative
  1311. deltas), local machine timezone, fixed offset timezone,
  1312. and UTC timezone.
  1313. ==== tzutc type ====
  1314. This type implements a basic UTC timezone. The constructor of this
  1315. type accepts no parameters.
  1316. ==== tzutc examples ====
  1317. {{{
  1318. >>> from datetime import *
  1319. >>> from dateutil.tz import *
  1320. >>> datetime.now()
  1321. datetime.datetime(2003, 9, 27, 9, 40, 1, 521290)
  1322. >>> datetime.now(tzutc())
  1323. datetime.datetime(2003, 9, 27, 12, 40, 12, 156379, tzinfo=tzutc())
  1324. >>> datetime.now(tzutc()).tzname()
  1325. 'UTC'
  1326. }}}
  1327. ==== tzoffset type ====
  1328. This type implements a fixed offset timezone, with no
  1329. support to daylight saving times. Here is the prototype of the
  1330. type constructor:
  1331. {{{
  1332. tzoffset(name, offset)
  1333. }}}
  1334. The {{{name}}} parameter may be optionally set to {{{None}}}, and
  1335. {{{offset}}} must be given in seconds.
  1336. ==== tzoffset examples ====
  1337. {{{
  1338. >>> from datetime import *
  1339. >>> from dateutil.tz import *
  1340. >>> datetime.now(tzoffset("BRST", -10800))
  1341. datetime.datetime(2003, 9, 27, 9, 52, 43, 624904,
  1342. tzinfo=tzinfo=tzoffset('BRST', -10800))
  1343. >>> datetime.now(tzoffset("BRST", -10800)).tzname()
  1344. 'BRST'
  1345. >>> datetime.now(tzoffset("BRST", -10800)).astimezone(tzutc())
  1346. datetime.datetime(2003, 9, 27, 12, 53, 11, 446419,
  1347. tzinfo=tzutc())
  1348. }}}
  1349. ==== tzlocal type ====
  1350. This type implements timezone settings as known by the
  1351. operating system. The constructor of this type accepts no
  1352. parameters.
  1353. ==== tzlocal examples ====
  1354. {{{
  1355. >>> from datetime import *
  1356. >>> from dateutil.tz import *
  1357. >>> datetime.now(tzlocal())
  1358. datetime.datetime(2003, 9, 27, 10, 1, 43, 673605,
  1359. tzinfo=tzlocal())
  1360. >>> datetime.now(tzlocal()).tzname()
  1361. 'BRST'
  1362. >>> datetime.now(tzlocal()).astimezone(tzoffset(None, 0))
  1363. datetime.datetime(2003, 9, 27, 13, 3, 0, 11493,
  1364. tzinfo=tzoffset(None, 0))
  1365. }}}
  1366. ==== tzstr type ====
  1367. This type implements timezone settings extracted from a
  1368. string in known TZ environment variable formats. Here is the prototype
  1369. of the constructor:
  1370. {{{
  1371. tzstr(str)
  1372. }}}
  1373. ==== tzstr examples ====
  1374. Here are examples of the recognized formats:
  1375. * {{{EST5EDT}}}
  1376. * {{{EST5EDT,4,0,6,7200,10,0,26,7200,3600}}}
  1377. * {{{EST5EDT,4,1,0,7200,10,-1,0,7200,3600}}}
  1378. * {{{EST5EDT4,M4.1.0/02:00:00,M10-5-0/02:00}}}
  1379. * {{{EST5EDT4,95/02:00:00,298/02:00}}}
  1380. * {{{EST5EDT4,J96/02:00:00,J299/02:00}}}
  1381. Notice that if daylight information is not present, but a
  1382. daylight abbreviation was provided, {{{tzstr}}} will follow the
  1383. convention of using the first sunday of April to start daylight
  1384. saving, and the last sunday of October to end it. If start or
  1385. end time is not present, 2AM will be used, and if the daylight
  1386. offset is not present, the standard offset plus one hour will
  1387. be used. This convention is the same as used in the GNU libc.
  1388. This also means that some of the above examples are exactly
  1389. equivalent, and all of these examples are equivalent
  1390. in the year of 2003.
  1391. Here is the example mentioned in the
  1392. [http://www.python.org/doc/current/lib/module-time.html time module documentation].
  1393. {{{
  1394. >>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
  1395. >>> time.tzset()
  1396. >>> time.strftime('%X %x %Z')
  1397. '02:07:36 05/08/03 EDT'
  1398. >>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
  1399. >>> time.tzset()
  1400. >>> time.strftime('%X %x %Z')
  1401. '16:08:12 05/08/03 AEST'
  1402. }}}
  1403. And here is an example showing the same information using {{{tzstr}}},
  1404. without touching system settings.
  1405. {{{
  1406. >>> tz1 = tzstr('EST+05EDT,M4.1.0,M10.5.0')
  1407. >>> tz2 = tzstr('AEST-10AEDT-11,M10.5.0,M3.5.0')
  1408. >>> dt = datetime(2003, 5, 8, 2, 7, 36, tzinfo=tz1)
  1409. >>> dt.strftime('%X %x %Z')
  1410. '02:07:36 05/08/03 EDT'
  1411. >>> dt.astimezone(tz2).strftime('%X %x %Z')
  1412. '16:07:36 05/08/03 AEST'
  1413. }}}
  1414. Are these really equivalent?
  1415. {{{
  1416. >>> tzstr('EST5EDT') == tzstr('EST5EDT,4,1,0,7200,10,-1,0,7200,3600')
  1417. True
  1418. }}}
  1419. Check the daylight limit.
  1420. {{{
  1421. >>> datetime(2003, 4, 6, 1, 59, tzinfo=tz).tzname()
  1422. 'EST'
  1423. >>> datetime(2003, 4, 6, 2, 00, tzinfo=tz).tzname()
  1424. 'EDT'
  1425. >>> datetime(2003, 10, 26, 0, 59, tzinfo=tz).tzname()
  1426. 'EDT'
  1427. >>> datetime(2003, 10, 26, 1, 00, tzinfo=tz).tzname()
  1428. 'EST'
  1429. }}}
  1430. ==== tzrange type ====
  1431. This type offers the same functionality as the {{{tzstr}}} type, but
  1432. instead of timezone strings, information is passed using
  1433. {{{relativedelta}}}s which are applied to a datetime set to the first
  1434. day of the year. Here is the prototype of this type's constructor:
  1435. {{{
  1436. tzrange(stdabbr, stdoffset=None, dstabbr=None, dstoffset=None,
  1437. start=None, end=None):
  1438. }}}
  1439. Offsets must be given in seconds. Information not provided will be
  1440. set to the defaults, as explained in the {{{tzstr}}} section above.
  1441. ==== tzrange examples ====
  1442. {{{
  1443. >>> tzstr('EST5EDT') == tzrange("EST", -18000, "EDT")
  1444. True
  1445. >>> from dateutil.relativedelta import *
  1446. >>> range1 = tzrange("EST", -18000, "EDT")
  1447. >>> range2 = tzrange("EST", -18000, "EDT", -14400,
  1448. ... relativedelta(hours=+2, month=4, day=1,
  1449. weekday=SU(+1)),
  1450. ... relativedelta(hours=+1, month=10, day=31,
  1451. weekday=SU(-1)))
  1452. >>> tzstr('EST5EDT') == range1 == range2
  1453. True
  1454. }}}
  1455. Notice a minor detail in the last example: while the DST should end
  1456. at 2AM, the delta will catch 1AM. That's because the daylight saving
  1457. time should end at 2AM standard time (the difference between STD and
  1458. DST is 1h in the given example) instead of the DST time. That's how
  1459. the {{{tzinfo}}} subtypes should deal with the extra hour that happens
  1460. when going back to the standard time. Check
  1461. [http://www.python.org/doc/current/lib/datetime-tzinfo.html tzinfo documentation]
  1462. for more information.
  1463. ==== tzfile type ====
  1464. This type allows one to use tzfile(5) format timezone files to extract
  1465. current and historical zone information. Here is the type constructor
  1466. prototype:
  1467. {{{
  1468. tzfile(fileobj)
  1469. }}}
  1470. Where {{{fileobj}}} is either a filename or a file-like object with
  1471. a {{{read()}}} method.
  1472. ==== tzfile examples ====
  1473. {{{
  1474. >>> tz = tzfile("/etc/localtime")
  1475. >>> datetime.now(tz)
  1476. datetime.datetime(2003, 9, 27, 12, 3, 48, 392138,
  1477. tzinfo=tzfile('/etc/localtime'))
  1478. >>> datetime.now(tz).astimezone(tzutc())
  1479. datetime.datetime(2003, 9, 27, 15, 3, 53, 70863,
  1480. tzinfo=tzutc())
  1481. >>> datetime.now(tz).tzname()
  1482. 'BRST'
  1483. >>> datetime(2003, 1, 1, tzinfo=tz).tzname()
  1484. 'BRDT'
  1485. }}}
  1486. Check the daylight limit.
  1487. {{{
  1488. >>> tz = tzfile('/usr/share/zoneinfo/EST5EDT')
  1489. >>> datetime(2003, 4, 6, 1, 59, tzinfo=tz).tzname()
  1490. 'EST'
  1491. >>> datetime(2003, 4, 6, 2, 00, tzinfo=tz).tzname()
  1492. 'EDT'
  1493. >>> datetime(2003, 10, 26, 0, 59, tzinfo=tz).tzname()
  1494. 'EDT'
  1495. >>> datetime(2003, 10, 26, 1, 00, tzinfo=tz).tzname()
  1496. 'EST'
  1497. }}}
  1498. ==== tzical type ====
  1499. This type is able to parse
  1500. [ftp://ftp.rfc-editor.org/in-notes/rfc2445.txt iCalendar]
  1501. style {{{VTIMEZONE}}} sessions into a Python timezone object.
  1502. The constuctor prototype is:
  1503. {{{
  1504. tzical(fileobj)
  1505. }}}
  1506. Where {{{fileobj}}} is either a filename or a file-like object with
  1507. a {{{read()}}} method.
  1508. ==== tzical methods ====
  1509. tzical.get(tzid=None)::
  1510. Since a single iCalendar file may contain more than one timezone,
  1511. you must ask for the timezone you want with this method. If there's
  1512. more than one timezone in the parsed file, you'll need to pass the
  1513. {{{tzid}}} parameter. Otherwise, leaving it empty will yield the only
  1514. available timezone.
  1515. ==== tzical examples ====
  1516. Here is a sample file extracted from the RFC. This file defines
  1517. the {{{EST5EDT}}} timezone, and will be used in the following example.
  1518. {{{
  1519. BEGIN:VTIMEZONE
  1520. TZID:US-Eastern
  1521. LAST-MODIFIED:19870101T000000Z
  1522. TZURL:http://zones.stds_r_us.net/tz/US-Eastern
  1523. BEGIN:STANDARD
  1524. DTSTART:19671029T020000
  1525. RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
  1526. TZOFFSETFROM:-0400
  1527. TZOFFSETTO:-0500
  1528. TZNAME:EST
  1529. END:STANDARD
  1530. BEGIN:DAYLIGHT
  1531. DTSTART:19870405T020000
  1532. RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
  1533. TZOFFSETFROM:-0500
  1534. TZOFFSETTO:-0400
  1535. TZNAME:EDT
  1536. END:DAYLIGHT
  1537. END:VTIMEZONE
  1538. }}}
  1539. And here is an example exploring a {{{tzical}}} type:
  1540. {{{
  1541. >>> from dateutil.tz import *; from datetime import *
  1542. >>> tz = tzical('EST5EDT.ics')
  1543. >>> tz.keys()
  1544. ['US-Eastern']
  1545. >>> est = tz.get('US-Eastern')
  1546. >>> est
  1547. <tzicalvtz 'US-Eastern'>
  1548. >>> datetime.now(est)
  1549. datetime.datetime(2003, 10, 6, 19, 44, 18, 667987,
  1550. tzinfo=<tzicalvtz 'US-Eastern'>)
  1551. >>> est == tz.get()
  1552. True
  1553. }}}
  1554. Let's check the daylight ranges, as usual:
  1555. {{{
  1556. >>> datetime(2003, 4, 6, 1, 59, tzinfo=est).tzname()
  1557. 'EST'
  1558. >>> datetime(2003, 4, 6, 2, 00, tzinfo=est).tzname()
  1559. 'EDT'
  1560. >>> datetime(2003, 10, 26, 0, 59, tzinfo=est).tzname()
  1561. 'EDT'
  1562. >>> datetime(2003, 10, 26, 1, 00, tzinfo=est).tzname()
  1563. 'EST'
  1564. }}}
  1565. ==== tzwin type ====
  1566. This type offers access to internal registry-based Windows timezones.
  1567. The constuctor prototype is:
  1568. {{{
  1569. tzwin(name)
  1570. }}}
  1571. Where {{{name}}} is the timezone name. There's a static {{{tzwin.list()}}}
  1572. method to check the available names,
  1573. ==== tzwin methods ====
  1574. tzwin.display()::
  1575. This method returns the timezone extended name.
  1576. tzwin.list()::
  1577. This static method lists all available timezone names.
  1578. ==== tzwin examples ====
  1579. {{{
  1580. >>> tz = tzwin("E. South America Standard Time")
  1581. }}}
  1582. ==== tzwinlocal type ====
  1583. This type offers access to internal registry-based Windows timezones.
  1584. The constructor accepts no parameters, so the prototype is:
  1585. {{{
  1586. tzwinlocal()
  1587. }}}
  1588. ==== tzwinlocal methods ====
  1589. tzwinlocal.display()::
  1590. This method returns the timezone extended name, and returns
  1591. {{{None}}} if one is not available.
  1592. ==== tzwinlocal examples ====
  1593. {{{
  1594. >>> tz = tzwinlocal()
  1595. }}}
  1596. ==== gettz() function ====
  1597. This function is a helper that will try its best to get the right
  1598. timezone for your environment, or for the given string. The prototype
  1599. is as follows:
  1600. {{{
  1601. gettz(name=None)
  1602. }}}
  1603. If given, the parameter may be a filename, a path relative to the base
  1604. of the timezone information path (the base could be
  1605. {{{/usr/share/zoneinfo}}}, for example), a string timezone
  1606. specification, or a timezone abbreviation. If {{{name}}} is not given,
  1607. and the {{{TZ}}} environment variable is set, it's used instead. If the
  1608. parameter is not given, and {{{TZ}}} is not set, the default tzfile
  1609. paths will be tried. Then, if no timezone information is found,
  1610. an internal compiled database of timezones is used. When running
  1611. on Windows, the internal registry-based Windows timezones are also
  1612. considered.
  1613. Example:
  1614. {{{
  1615. >>> from dateutil.tz import *
  1616. >>> gettz()
  1617. tzfile('/etc/localtime')
  1618. >>> gettz("America/Sao Paulo")
  1619. tzfile('/usr/share/zoneinfo/America/Sao_Paulo')
  1620. >>> gettz("EST5EDT")
  1621. tzfile('/usr/share/zoneinfo/EST5EDT')
  1622. >>> gettz("EST5")
  1623. tzstr('EST5')
  1624. >>> gettz('BRST')
  1625. tzlocal()
  1626. >>> os.environ["TZ"] = "America/Sao Paulo"
  1627. >>> gettz()
  1628. tzfile('/usr/share/zoneinfo/America/Sao_Paulo')
  1629. >>> os.environ["TZ"] = "BRST"
  1630. >>> gettz()
  1631. tzlocal()
  1632. >>> gettz("Unavailable")
  1633. >>>
  1634. }}}
  1635. === zoneinfo ===
  1636. This module provides direct access to the internal compiled
  1637. database of timezones. The timezone data and the compiling tools
  1638. are obtained from the following project:
  1639. http://www.twinsun.com/tz/tz-link.htm
  1640. ==== gettz() function ====
  1641. This function will try to retrieve the given timezone information
  1642. from the internal compiled database, and will cache its results.
  1643. Example:
  1644. {{{
  1645. >>> from dateutil import zoneinfo
  1646. >>> zoneinfo.gettz("Brazil/East")
  1647. tzfile('Brazil/East')
  1648. }}}
  1649. ## vim:ft=moin