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`ISO year week number notation <https://www.cl.cam.ac.uk/~mgk25/iso-time.html>`_
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