Parameters of timedelta in Python
The timedelta class accepts the following parameters:
- days: Integer value representing the number of days.
- seconds: Integer value representing the number of seconds.
- microseconds: Integer value representing the number of microseconds.
- milliseconds: Integer value representing the number of milliseconds (1 millisecond = 1000 microseconds).
- minutes: Integer value representing the number of minutes (1 minute = 60 seconds).
- hours: Integer value representing the number of hours (1 hour = 60 minutes).
- weeks: Integer value representing the number of weeks (1 week = 7 days).
All parameters are optional, and their default value is 0. The values are converted internally into days, seconds, and microseconds.
Return Value of timedelta in Python
The timedelta function returns a timedelta object representing the difference between two datetime or date objects. It does not return a string or integer but rather an instance of timedelta, which can be used for further calculations.
Examples
Example 1: Creating a timedelta object
from datetime import timedelta
time_gap = timedelta(days=2, hours=5, minutes=30)
print("Time gap:", time_gap)
You can also try this code with Online Python Compiler
Output:
Time gap: 2 days, 5:30:00
In this example, we create a timedelta object representing 2 days, 5 hours, and 30 minutes.
Example 2: Subtracting timedelta from current datetime
from datetime import datetime, timedelta
current_time = datetime.now()
previous_time = current_time - timedelta(days=3, hours=4)
print("Current time:", current_time)
print("Time 3 days and 4 hours ago:", previous_time)
You can also try this code with Online Python Compiler
Output:
Current time: 2025-03-08 12:45:30.123456
Time 3 days and 4 hours ago: 2025-03-05 08:45:30.123456
Here, we subtract 3 days and 4 hours from the current date and time.
Related Functions in Python
The datetime module provides several functions that work with timedelta. Some important ones include:
- datetime.now() – Returns the current local date and time.
- datetime.today() – Returns the current date without the time.
- date.today() – Returns the current date (without time) as a date object.
- datetime.combine(date, time) – Combines a date and time object into a datetime object.
- datetime.strftime(format) – Converts a datetime object into a formatted string.
Example 3: Using timedelta with datetime.now()
from datetime import datetime, timedelta
current_time = datetime.now()
future_time = current_time + timedelta(days=7)
print("Current time:", current_time)
print("Time after 7 days:", future_time)
You can also try this code with Online Python Compiler
Output:
Current time: 2025-03-08 12:50:30.123456
Time after 7 days: 2025-03-15 12:50:30.123456
Here, we add 7 days to the current date and time.
Time & Space Complexity
Time Complexity
Timedelta operations like addition, subtraction, & comparison are very efficient. These operations typically run in O(1) time complexity. This means the time taken to perform these operations doesn’t depend on the size of the data. Whether you’re adding 5 days or 500 days, the operation takes the same amount of time.
For example:
from datetime import datetime, timedelta
Create two timedelta objects
delta1 = timedelta(days=10, hours=5)
delta2 = timedelta(days=3, hours=12)
Perform addition
result = delta1 + delta2
print("Sum of timedelta:", result)
Here, adding `delta1` & `delta2` is a constant-time operation, regardless of the values.
Space Complexity
Timedelta objects are lightweight in terms of memory usage. They store only the difference in days, seconds, & microseconds. The space complexity is O(1) because the memory required doesn’t grow with the size of the input.
For example:
from datetime import timedelta
Create a timedelta object
delta = timedelta(days=365, hours=12, minutes=30)
Print the timedelta
print("Timedelta:", delta)
This `timedelta` object uses a fixed amount of memory, no matter how large or small the time difference is.
Why Does This Matter?
Understanding time & space complexity helps you write efficient code. If you’re building an application that involves frequent date & time calculations, timedelta’s O(1) performance ensures your program runs smoothly without unnecessary delays or memory usage.
Quick Tips When Using Timedelta
Using timedelta effectively can save you time & make your code cleaner. Let’s discuss some quick tips to help you get the most out of it:
1. Always Import the Required Modules
Make sure to import `timedelta` & `datetime` from the `datetime` module. Without this, your code won’t work.
from datetime import datetime, timedelta
2. Use Keyword Arguments for Clarity
When creating a `timedelta` object, use keyword arguments like `days`, `hours`, `minutes`, etc. This makes your code easier to read & understand.
Clear & readable
time_diff = timedelta(days=2, hours=5, minutes=30)
Less readable
time_diff = timedelta(2, 19800) 2 days & 19800 seconds (5 hours & 30 minutes)
3. Handle Negative Values for Past Dates
Timedelta supports negative values, which is useful for calculating past dates.
Current date & time
now = datetime.now()
Subtract 3 days
past_date = now - timedelta(days=3)
print("Date 3 days ago:", past_date)
4. Combine Timedelta with Other Date Operations
You can use timedelta with other `datetime` operations to perform complex calculations. For example, finding the difference between two dates:
Two dates
date1 = datetime(2023, 10, 1)
date2 = datetime(2023, 10, 10)
Calculate the difference
difference = date2 - date1
print("Difference between dates:", difference)
5. Convert Timedelta to Specific Units
If you need the difference in specific units (like hours or minutes), you can convert the `timedelta` object.
Create a timedelta
time_diff = timedelta(days=1, hours=6)
Convert to hours
total_hours = time_diff.total_seconds() / 3600
print("Total hours:", total_hours)
6. Avoid Mixing Incompatible Types
Timedelta works only with `datetime` objects. Don’t try to use it with strings or other data types without converting them first.
Correct way
date_str = "2023-10-01"
date_obj = datetime.strptime(date_str, "%Y-%m-%d")
new_date = date_obj + timedelta(days=7)
print("New date:", new_date)
7. Use Timedelta for Scheduling Tasks
Timedelta is great for scheduling tasks or events in the future.
Schedule a task 2 weeks from now
current_time = datetime.now()
task_time = current_time + timedelta(weeks=2)
print("Task scheduled for:", task_time)
Frequently Asked Questions
What is timedelta used for in Python?
timedelta in Python is used for representing differences between two dates or times. It allows operations like adding or subtracting time intervals from datetime objects.
Can timedelta represent months or years?
No, timedelta does not support months or years directly because they vary in length. Instead, it works with days, seconds, minutes, hours, and weeks.
How can I convert a timedelta object to seconds?
You can use the .total_seconds() method to get the total number of seconds in a timedelta object.
Conclusion
In this article, we learned the datetime.timedelta() function in Python, which is used to represent the difference between two dates or times. It allows us to perform operations like adding or subtracting time intervals in days, hours, minutes, and seconds. This function is essential for date manipulation, scheduling, and time-based calculations in Python applications.
Recommended Readings:
19+ registered 
