Python timedelta object is used to perform datetime manipulations in an easy way. The timedelta class is part of datetime module.
Pythoon timedelta
Python timedelta object represents a duration of time. We can create its object using following factory method.
1 2 3 |
datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0) |
Note that timedelta() function takes keyword arguments. All arguments are optional and default to 0. Arguments may be integers or floats and may be positive or negative.
The timedelta object supports mathematical operations such as addition, subtraction, multiplication etc. using basic operators, so it’s very easy to use it. It’s mostly used to get a datetime object with some delta date and time.
Python timedelta example
Let’s have a look at some examples of getting future dates and past dates using timedelta object.
1 2 3 4 5 6 7 8 9 10 11 |
from datetime import datetime, timedelta current_datetime = datetime.now() # future dates one_year_future_date = current_datetime + timedelta(days=365) print('Current Date:', current_datetime) print('One year from now Date:', one_year_future_date) # past dates three_days_before_date = current_datetime - timedelta(days=3) print('Three days before Date:', three_days_before_date) |
Output:
1 2 3 4 5 |
Current Date: 2018-09-18 12:33:30.656394 One year from now Date: 2019-09-18 12:33:30.656394 Three days before Date: 2018-09-15 12:33:30.656394 |
Python timedelta with date and time
Python timedelta supports addition and subtraction with date object too.
1 2 3 4 5 6 |
dt = current_datetime.date() print('Current Date:', dt) dt_tomorrow = dt + timedelta(days=1) print('Tomorrow Date:', dt_tomorrow) |
Output:
1 2 3 4 |
Current Date: 2018-09-18 Tomorrow Date: 2018-09-19 |
However, timedelta doesn’t support the same operations with time object.
1 2 3 4 5 |
tm = current_datetime.time() print('Current Time:', tm) tm_after_30_mins = tm + timedelta(minutes=30) |
Above code will produce the following error message.
1 2 3 |
TypeError: unsupported operand type(s) for +: 'datetime.time' and 'datetime.timedelta' |
Python timedelta attributes
Python timedelta class has three attributes.
1 2 3 4 5 |
print(timedelta.max) print(timedelta.min) print(timedelta.resolution) |
Output:
1 2 3 4 5 |
999999999 days, 23:59:59.999999 -999999999 days, 0:00:00 0:00:00.000001 |
Python timedelta total seconds
Python timedelta object total_seconds() method returns the total number of seconds.
1 2 3 |
print('Seconds in an year:', timedelta(days=365).total_seconds()) |
Output: Seconds in an year: 31536000.0
Python timedelta operations
Let’s look at some more operations between timedelta objects.
1 2 3 4 5 6 7 8 9 10 |
ct = current_datetime + timedelta(seconds=60) - timedelta(seconds=60) print(current_datetime == ct) ct = current_datetime + timedelta(seconds=10) * 6 print('Current Time:', current_datetime) print('One Min from Current Time:', ct) print('Timedelta absolute value:', abs(timedelta(days=-10))) print('Timedelta String Representation:', str(timedelta(days=1, seconds=30, hours=10, milliseconds=300))) print('Timedelta Object Representation:', repr(timedelta(days=1, seconds=30, hours=10, milliseconds=300))) |
Output:
1 2 3 4 5 6 7 8 |
True Current Time: 2018-09-18 12:47:28.331197 One Min from Current Time: 2018-09-18 12:48:28.331197 Timedelta absolute value: 10 days, 0:00:00 Timedelta String Representation: 1 day, 10:00:30.300000 Timedelta Object Representation: datetime.timedelta(days=1, seconds=36030, microseconds=300000) |
Summary
Python timedelta object is very useful for datetime manipulations. The support for basic arithmetic operators makes it very easy to use.
Reference: Official Documentation