timedelta class in Python

timedelta class represents a time duration. The time duration could be positive or negative. timedelta class helps holding time intervals up to microseconds precision. It also allows arithmetic operations on the time intervals and allows comparison of them.

Timedelta Updated 20 Jan 2019 4 min read

Overview

  • The difference delta between two quantities of date or time is provided by the class datetime.timedelta. The difference could be positive or negative.

  • The timedelta can be created in several ways:

  1. By using the timedelta constructor:

The timedelta constructor takes several arguments, which include weeks, days, hours, minutes, seconds, milliseconds and microseconds. The order in which these arguments are expected in the constructor could be different than the order stated in the previous sentence. All these arguments have a default value of zero. Hence by passing no values to the constructor of timedelta class a timedelta object that corresponds to a zero time difference is created.

Example 1:

python
import datetime

# Representing a duration of 1 day 1 second and 1 microsecond

t1 = datetime.timedelta(1, 1, 1)

# Representing a duration of 2 days 2 seconds and 2 microseconds

t2 = datetime.timedelta(2, 2, 2)

# Print the time difference between the second time duration and the first time duration

timeDiff = t2-t1

print(timeDiff)

Output:

Output
1 day, 0:00:01.000001

2.As the result of a timedelta arithmetic operation

  • Timedelta objects can be added, subtracted, multiplied, divided and compared. In the Python example below two timedelta objects are added to produce another timedelta object.

Example 2:

python
import datetime

# Two time durations are added and the result is printed

duration1 = datetime.timedelta(hours=3)

duration2 = datetime.timedelta(hours=1)

duration3 = duration1 + duration2

print("Duration3 = Duration1+Duration2")

print("Duration3 = %s"%(duration3))

# Two time durations are compared

print("First time duration is less than the second time duration:%s"%(duration1 < duration2))

Output:

Output
Duration3 = Duration1+Duration2

Duration3 = 4:00:00

First time duration is less than the second time duration:False
Attributes of a datetime.timedelta object
AttributeDescription
timedelta.minRepresents the most negative timedelta object. A timedelta object with -999999999 days as the duration. Any further increase by a microsecond will cause an overflow in the magnitude.
timedelta.maxRepresents the most positive timedelta object. A timedelta object with duration of 999999999 days, 23 hours, 59 minutes, 59 seconds, 999999 microseconds. Any further addition of a microsecond will result in the overflow of the magnitude.
timedelta.resolutionRepresents the smallest difference between two timedelta objects that are not equal. This is currently equal to 1 microsecond.
Python Functions/Operations supported on a timedelta object
Addition (+)Adds two timedelta objects and returns the resultant timedelta object.
Subtraction(-)Subtracts one timedelta object from another timedelta object and returns the resultant timedelta object.
Multiplication(*)Multiplies one timedelta object by an integer or a floating-point number, and returns the resultant timedelta object.
Division(/)Divides one timedelta object by another timedelta object and returns the resultant value as a floating-point number.
Divides one timedelta object by an integer or a floating-point number and returns the resultant value as a timedelta object.
Division(//)Divides one timedelta object by another timedelta object, floor is computed on the quotient and returns the resultant value as an integer.
Divides the timedelta object by an integer and returns the result as a timedelta object.
Modulo Division (%)Divides one timedelta object by another timedelta object and returns the remainder as the resultant timedelta object.
abs(timeDeltaObject)Returns the magnitude of the time duration represented by the timedelta object.
str(timeDeltaObject)Returns the time duration in the form of n days,HH:MM:SS.[microseconds in 6 digits]
repr(timeDeltaObject)Returns the string representation of the timedelta object in the form of the actual constructor call that creates the object.
Methods of a datetime.timedelta object
Method NameDescription
total_seconds()Returns the duration represented by the timedelta object as number of seconds.

timedelta operations involving date, datetime objects

It is worthwhile to note here that timedelta objects can be added with a datetime object or a date object to perform related arithmetic.

python
Example:

import datetime

# Create a time duration of one hour

timeDelta   = datetime.timedelta(hours=1)

# Create a date

today       = datetime.datetime(3019, 1, 20)

# Increase a time duration of one hour

oneAM       = today+timeDelta

print("Date : %s"%(today))

print("Date + 1 hour : %s"%(oneAM))

Output:

Date : 3019-01-20 00:00:00

Date + 1 hour : 3019-01-20 01:00:00
import datetime

# Create a time duration of one hour

timeDelta   = datetime.timedelta(hours=1)

# Create a date

today       = datetime.datetime(3019, 1, 20)

# Increase a time duration of one hour

oneAM       = today+timeDelta

print("Date : %s"%(today))

print("Date + 1 hour : %s"%(oneAM))
Date : 3019-01-20 00:00:00

Date + 1 hour : 3019-01-20 01:00:00