1============= 2relativedelta 3============= 4.. automodule:: dateutil.relativedelta 5 :members: 6 :undoc-members: 7 8.. testsetup:: relativedelta 9 10Examples 11-------- 12 13 >>> from datetime import *; from dateutil.relativedelta import * 14 >>> import calendar 15 >>> NOW = datetime(2003, 9, 17, 20, 54, 47, 282310) 16 >>> TODAY = date(2003, 9, 17) 17 18Let's begin our trip:: 19 20 >>> from datetime import *; from dateutil.relativedelta import * 21 >>> import calendar 22 23Store some values:: 24 25 >>> NOW = datetime.now() 26 >>> TODAY = date.today() 27 >>> NOW 28 datetime.datetime(2003, 9, 17, 20, 54, 47, 282310) 29 >>> TODAY 30 datetime.date(2003, 9, 17) 31 32Next month 33 34.. doctest:: relativedelta 35 36 >>> NOW+relativedelta(months=+1) 37 datetime.datetime(2003, 10, 17, 20, 54, 47, 282310) 38 39Next month, plus one week. 40 41.. doctest:: relativedelta 42 43 >>> NOW+relativedelta(months=+1, weeks=+1) 44 datetime.datetime(2003, 10, 24, 20, 54, 47, 282310) 45 46Next month, plus one week, at 10am. 47 48.. doctest:: relativedelta 49 50 >>> TODAY+relativedelta(months=+1, weeks=+1, hour=10) 51 datetime.datetime(2003, 10, 24, 10, 0) 52 53Here is another example using an absolute relativedelta. Notice the use of 54year and month (both singular) which causes the values to be *replaced* in the 55original datetime rather than performing an arithmetic operation on them. 56 57.. doctest:: relativedelta 58 59 >>> NOW+relativedelta(year=1, month=1) 60 datetime.datetime(1, 1, 17, 20, 54, 47, 282310) 61 62Let's try the other way around. Notice that the 63hour setting we get in the relativedelta is relative, 64since it's a difference, and the weeks parameter 65has gone. 66 67.. doctest:: relativedelta 68 69 >>> relativedelta(datetime(2003, 10, 24, 10, 0), TODAY) 70 relativedelta(months=+1, days=+7, hours=+10) 71 72One month before one year. 73 74.. doctest:: relativedelta 75 76 >>> NOW+relativedelta(years=+1, months=-1) 77 datetime.datetime(2004, 8, 17, 20, 54, 47, 282310) 78 79How does it handle months with different numbers of days? 80Notice that adding one month will never cross the month 81boundary. 82 83.. doctest:: relativedelta 84 85 >>> date(2003,1,27)+relativedelta(months=+1) 86 datetime.date(2003, 2, 27) 87 >>> date(2003,1,31)+relativedelta(months=+1) 88 datetime.date(2003, 2, 28) 89 >>> date(2003,1,31)+relativedelta(months=+2) 90 datetime.date(2003, 3, 31) 91 92The logic for years is the same, even on leap years. 93 94.. doctest:: relativedelta 95 96 >>> date(2000,2,28)+relativedelta(years=+1) 97 datetime.date(2001, 2, 28) 98 >>> date(2000,2,29)+relativedelta(years=+1) 99 datetime.date(2001, 2, 28) 100 101 >>> date(1999,2,28)+relativedelta(years=+1) 102 datetime.date(2000, 2, 28) 103 >>> date(1999,3,1)+relativedelta(years=+1) 104 datetime.date(2000, 3, 1) 105 106 >>> date(2001,2,28)+relativedelta(years=-1) 107 datetime.date(2000, 2, 28) 108 >>> date(2001,3,1)+relativedelta(years=-1) 109 datetime.date(2000, 3, 1) 110 111Next friday 112 113.. doctest:: relativedelta 114 115 >>> TODAY+relativedelta(weekday=FR) 116 datetime.date(2003, 9, 19) 117 118 >>> TODAY+relativedelta(weekday=calendar.FRIDAY) 119 datetime.date(2003, 9, 19) 120 121Last friday in this month. 122 123.. doctest:: relativedelta 124 125 >>> TODAY+relativedelta(day=31, weekday=FR(-1)) 126 datetime.date(2003, 9, 26) 127 128Next wednesday (it's today!). 129 130.. doctest:: relativedelta 131 132 >>> TODAY+relativedelta(weekday=WE(+1)) 133 datetime.date(2003, 9, 17) 134 135Next wednesday, but not today. 136 137.. doctest:: relativedelta 138 139 >>> TODAY+relativedelta(days=+1, weekday=WE(+1)) 140 datetime.date(2003, 9, 24) 141 142Following 143[http://www.cl.cam.ac.uk/~mgk25/iso-time.html ISO year week number notation] 144find the first day of the 15th week of 1997. 145 146.. doctest:: relativedelta 147 148 >>> datetime(1997,1,1)+relativedelta(day=4, weekday=MO(-1), weeks=+14) 149 datetime.datetime(1997, 4, 7, 0, 0) 150 151How long ago has the millennium changed? 152 153.. doctest:: relativedelta 154 :options: +NORMALIZE_WHITESPACE 155 156 >>> relativedelta(NOW, date(2001,1,1)) 157 relativedelta(years=+2, months=+8, days=+16, 158 hours=+20, minutes=+54, seconds=+47, microseconds=+282310) 159 160How old is John? 161 162.. doctest:: relativedelta 163 :options: +NORMALIZE_WHITESPACE 164 165 >>> johnbirthday = datetime(1978, 4, 5, 12, 0) 166 >>> relativedelta(NOW, johnbirthday) 167 relativedelta(years=+25, months=+5, days=+12, 168 hours=+8, minutes=+54, seconds=+47, microseconds=+282310) 169 170It works with dates too. 171 172.. doctest:: relativedelta 173 174 >>> relativedelta(TODAY, johnbirthday) 175 relativedelta(years=+25, months=+5, days=+11, hours=+12) 176 177Obtain today's date using the yearday: 178 179.. doctest:: relativedelta 180 181 >>> date(2003, 1, 1)+relativedelta(yearday=260) 182 datetime.date(2003, 9, 17) 183 184We can use today's date, since yearday should be absolute 185in the given year: 186 187.. doctest:: relativedelta 188 189 >>> TODAY+relativedelta(yearday=260) 190 datetime.date(2003, 9, 17) 191 192Last year it should be in the same day: 193 194.. doctest:: relativedelta 195 196 >>> date(2002, 1, 1)+relativedelta(yearday=260) 197 datetime.date(2002, 9, 17) 198 199But not in a leap year: 200 201.. doctest:: relativedelta 202 203 >>> date(2000, 1, 1)+relativedelta(yearday=260) 204 datetime.date(2000, 9, 16) 205 206We can use the non-leap year day to ignore this: 207 208.. doctest:: relativedelta 209 210 >>> date(2000, 1, 1)+relativedelta(nlyearday=260) 211 datetime.date(2000, 9, 17) 212