What is the difference between "datetime.timedelta" and "dateutil.relativedelta.relativedelta" when working only with days?

Question

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)

Answer 1

According to https://seihotech.com/comparing-datetime-timedelta-and-dateutil-relativedelta-relativedelta-in-python/

datetime.timedelta 

• a function from the Python standard library
• only works with days

dateutil.relativedelta.relativedelta 

• a third-party module
• can work with other date components: eg: hours, minutes, and seconds

Answer 2

As @julien mentioned, timedelta is an order of magnitude faster than relativedelta. Here is a simple demonstration using days:

In [1]: from datetime import date, timedelta
   ...: from dateutil.relativedelta import *
   ...: import timeit

In [2]: def td():
   ...:     return date.today() + timedelta(days=7)
   ...:

In [3]: def rd():
   ...:     return date.today() + relativedelta(days=7)
   ...:

In [4]: timeit.timeit('td()', 'from __main__ import td', number=1000)
Out[4]: 0.0019557802006602287

In [5]: timeit.timeit('rd()', 'from __main__ import rd', number=1000)
Out[5]: 0.014670956879854202

If performance is important relativedelta should be avoided, unless the task cannot be accomplished using timedelta (such as adding a week/month/year delta).

Answer 3

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.

Answer 4

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.

Answer 5

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)