98
votes

What is the difference between datetime.timedelta (from Python's standard library) and dateutil.relativedelta.relativedelta when working only with days?

As far as I understand, timedelta only supports days (and weeks), while relativedelta adds support for periods defined in terms of years, months, weeks or days, as well as defining absolute values for year, month or day. (remember, for the purposes of this question, I don't have to worry about hours, minutes or seconds)

Considering that I'm only working with datetime.date objects, and only interested in periods defined by the number of days, what's the difference between timedelta and relativedelta? Is there any difference?

from datetime import date, timedelta
from dateutil.relativedelta import relativedelta

i = -1  # This could have been any integer, positive or negative
someday = date.today()
# Is there any difference between these two lines?
otherday = someday + timedelta(days=i)
otherday = someday + relativedelta(days=i)
3
If you are only interested in deltas in days between dates, just use the standard library's dateime.timedelta which will achieve what you want and avoid the dependency on the external dateutil package.Pedro Romano
It is worth saying that on top of saving one extra dependency, computing deltas in days between dates is multiple times faster with timedelta than relativedelta. (~10 times)Julien B.

3 Answers

82
votes

dateutil is an extension package to the python standard datetime module. As you say, it provides extra functionality, such as timedeltas that are expressed in units larger than a day.

This is useful if you have to ask questions such as how many months can I save before my girlfriend's birthday comes up, or what's the last Friday in the month? This hides complex calculations that are caused by the different lengths of the months, or extra days in leap years.

In your case, you are only interested in the number of days. So you'd best use timedelta as this avoids an extra dependency on the dateutil package.

38
votes

A relativedelta has many more parameters than a timedelta:

Definition:   relativedelta.relativedelta(self, dt1=None, dt2=None,
years=0, months=0, days=0, leapdays=0, weeks=0, hours=0, minutes=0,
seconds=0, microseconds=0, year=None, month=None, day=None,
weekday=None, yearday=None, nlyearday=None, hour=None, minute=None,
second=None, microsecond=None)

with which you can do things like calculate the last Friday in a month:

In [14]: import datetime as dt

In [15]: import dateutil.relativedelta as relativedelta

In [16]: today = dt.date.today()

In [17]: rd = relativedelta.relativedelta(day = 31, weekday = relativedelta.FR(-1))

In [18]: today+rd
Out[18]: datetime.date(2012, 9, 28)
16
votes

One major difference not highlighted in other answers is the presence of singular and plural nouns for each time difference primitive. While timedelta only offers plural nouns (e.g. hours, days) to denote relative time difference, relativedelta offers singular nouns as well (e.g. hour, day) to denote absolute time information.

This is clear from the definition of the 2 classes:

Definition:   datetime.timedelta([days[, seconds[, microseconds[, 
milliseconds[, minutes[, hours[, weeks]]]]]]])

Definition:   relativedelta.relativedelta(self, dt1=None, dt2=None,
years=0, months=0, days=0, leapdays=0, weeks=0, hours=0, minutes=0,
seconds=0, microseconds=0, year=None, month=None, day=None,
weekday=None, yearday=None, nlyearday=None, hour=None, minute=None,
second=None, microsecond=None)

Now, exactly what does the singular form do? Singular form creates a delta which when added to a datetime object, sets that specific date/time primitive in the datetime object to that mentioned in the relativedelta. Here is a small example:

>>> import datetime as dt; from dateutil.relativedelta import *
>>> NOW = dt.datetime(2018, 11, 17, 9, 6, 31)
>>> NOW
datetime.datetime(2018, 11, 17, 9, 6, 31)
>>> NOW + relativedelta(hours=1) #Simply add one hour
datetime.datetime(2018, 11, 17, 10, 6, 31)
>>> NOW + relativedelta(hour=1) #Set the hour to 01:00 am
datetime.datetime(2018, 11, 17, 1, 6, 31)

This can lead to relativedelta being used for some interesting applications, which can be complicated to implement using timedelta. One that quickly comes to mind is rounding-off.

An Interesting Application : Quickly Rounding off

I will now show you how relativedelta is more expressive when doing rounding off a datetime object to the nearest minute, hour, day etc.

Rounding off to the nearest hour:

Notice how straightforward it is to round-off using relativedelta:

#Using `relativedelta`
NOW + relativedelta(hours=1, minute=0, second=0, microsecond=0)

#Using `timedelta`
dt.combine(NOW.date(),dt.time(NOW.hour,0,0)) + dt.timedelta(0,60*60,0)

Other more complicated rounding-offs are easily achievable using relativedelta. However, note that all the round-offs that can be done by relativedelta can also be done using datetime functions and timedelta, only in a slightly more convoluted way.