1 ============= 2 relativedelta 3 ============= 4 .. automodule:: dateutil.relativedelta 5 :members: 6 :undoc-members: 7 8 .. testsetup:: relativedelta 9 10 Examples 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 18 Let's begin our trip:: 19 20 >>> from datetime import *; from dateutil.relativedelta import * 21 >>> import calendar 22 23 Store 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 32 Next month 33 34 .. doctest:: relativedelta 35 36 >>> NOW+relativedelta(months=+1) 37 datetime.datetime(2003, 10, 17, 20, 54, 47, 282310) 38 39 Next 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 46 Next 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 53 Here is another example using an absolute relativedelta. Notice the use of 54 year and month (both singular) which causes the values to be *replaced* in the 55 original 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 62 Let's try the other way around. Notice that the 63 hour setting we get in the relativedelta is relative, 64 since it's a difference, and the weeks parameter 65 has gone. 66 67 .. doctest:: relativedelta 68 69 >>> relativedelta(datetime(2003, 10, 24, 10, 0), TODAY) 70 relativedelta(months=+1, days=+7, hours=+10) 71 72 One 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 79 How does it handle months with different numbers of days? 80 Notice that adding one month will never cross the month 81 boundary. 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 92 The 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 111 Next 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 121 Last friday in this month. 122 123 .. doctest:: relativedelta 124 125 >>> TODAY+relativedelta(day=31, weekday=FR(-1)) 126 datetime.date(2003, 9, 26) 127 128 Next wednesday (it's today!). 129 130 .. doctest:: relativedelta 131 132 >>> TODAY+relativedelta(weekday=WE(+1)) 133 datetime.date(2003, 9, 17) 134 135 Next wednesday, but not today. 136 137 .. doctest:: relativedelta 138 139 >>> TODAY+relativedelta(days=+1, weekday=WE(+1)) 140 datetime.date(2003, 9, 24) 141 142 Following 143 [http://www.cl.cam.ac.uk/~mgk25/iso-time.html ISO year week number notation] 144 find 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 151 How 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 160 How 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 170 It works with dates too. 171 172 .. doctest:: relativedelta 173 174 >>> relativedelta(TODAY, johnbirthday) 175 relativedelta(years=+25, months=+5, days=+11, hours=+12) 176 177 Obtain 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 184 We can use today's date, since yearday should be absolute 185 in the given year: 186 187 .. doctest:: relativedelta 188 189 >>> TODAY+relativedelta(yearday=260) 190 datetime.date(2003, 9, 17) 191 192 Last 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 199 But 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 206 We 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
