Math with dates in Python is both simple and powerful — using timedelta objects, you can add or subtract days, weeks, hours, minutes, seconds, or microseconds from date or datetime objects, and compute the exact time difference between two dates. The datetime module handles edge cases like leap years, month boundaries, and daylight saving transitions (when time zones are used). In 2026, date arithmetic is essential for scheduling, age calculations, time deltas in logs, financial due dates, data filtering by periods, and any application involving timelines or durations — all done cleanly and accurately without manual day counting.
Here’s a complete, practical guide to math with dates: adding/subtracting time, calculating differences, real-world patterns, handling edge cases, and modern best practices with type hints, time zones, and pandas/Polars integration.
Basic arithmetic uses timedelta — add or subtract to shift a date/datetime forward or backward.
from datetime import date, datetime, timedelta
# Date example
d = date(2026, 2, 10)
next_day = d + timedelta(days=1)
print(next_day) # 2026-02-11
one_week_ago = d - timedelta(weeks=1)
print(one_week_ago) # 2026-02-03
# Datetime example
dt = datetime(2026, 2, 10, 14, 30)
future = dt + timedelta(hours=2, minutes=30)
print(future) # 2026-02-10 17:00:00
past = dt - timedelta(days=3, hours=5)
print(past) # 2026-02-07 09:30:00
Differences between two dates/datetimes return a timedelta object — access days, seconds, microseconds for precise intervals.
start = date(2026, 1, 1)
end = date(2026, 4, 1)
delta = end - start
print(delta) # 90 days, 0:00:00
print(delta.days) # 90
print(delta.total_seconds()) # 7776000.0 (90 days in seconds)
# With time
dt1 = datetime(2026, 2, 10, 10, 0)
dt2 = datetime(2026, 2, 11, 14, 30)
time_delta = dt2 - dt1
print(time_delta) # 1 day, 4:30:00
print(time_delta.days, time_delta.seconds / 3600) # 1 4.5
Real-world pattern: calculating ages, due dates, or time since event — very common in user profiles, subscriptions, analytics, and reminders.
# Age in years (approximate)
birthdate = date(1990, 5, 15)
today = date.today()
age_years = (today - birthdate).days // 365.25
print(f"Age: {age_years} years") # e.g., 35 years
# Days until deadline
deadline = date(2026, 12, 31)
days_left = (deadline - today).days
print(f"Days left: {days_left}")
Best practices make date math safe, readable, and performant. Use timedelta for all additions/subtractions — never manual day/month/year math (leap years, DST). Prefer date.today() or datetime.now(tz=ZoneInfo("UTC")) for current time — avoid naive local time in production. Handle zero/negative deltas — if delta.days > 0 for future checks. Modern tip: use Polars for large timestamp columns — pl.col("date") + pl.duration(days=7) or pl.col("end") - pl.col("start") is 10–100× faster than pandas loops. Add type hints — date, datetime, timedelta — improves readability and mypy checks. For time zones, use zoneinfo (Python 3.9+) — datetime.now(ZoneInfo("America/New_York")) — avoids pytz issues. Combine with pandas — df['due_date'] = df['start_date'] + pd.Timedelta(days=30) — vectorized and fast. Wrap arithmetic over user input in try/except ValueError — invalid dates raise errors. Use relativedelta from dateutil for month/year jumps — date + relativedelta(months=3) — handles month-end correctly.
Math with dates using timedelta is clean, accurate, and powerful — add/subtract time, compute durations, and handle real-world time logic without bugs. In 2026, use UTC, explicit time zones, type hints, and Polars for scale. Master date arithmetic, and you’ll build reliable scheduling, analytics, and time-based features effortlessly.
Next time you need to shift a date, find days between events, or calculate ages — reach for timedelta. It’s Python’s cleanest way to do date math — correctly and efficiently.