Durations and Intervals

So far a date or time has been a single point. Real programs mostly care about spans: how long something took, whether two bookings collide, which hours are free, how many events landed in each hour. This chapter covers the timedelta type in more detail, then builds the standard interval tools from a few lines each. Every snippet below was run with Python 3.14; the comments show what was printed.

What a timedelta Really Holds

A timedelta stores exactly three numbers: days, seconds and microseconds. Whatever you pass in is normalised into those, and the seconds and microseconds are always non-negative. That has one surprising consequence for negative durations:

Minus one hour is stored as "minus one day, plus 23 hours". It is correct, but printing it is confusing, and .seconds is not the total. The attributes .days, .seconds and .microseconds are the stored parts, not a breakdown for display. .seconds is never more than 86399, so it is not "the number of seconds" in a long duration. Use total_seconds() whenever you want one number.

Dividing and Formatting Durations

Dividing a timedelta by another timedelta tells you how many of one fit in the other. Floor division gives a whole count, modulo gives the remainder, and true division gives a float:

The built-in str() switches to "N days, H:MM:SS" once a duration passes 24 hours, which suits logs but not a timer display. The helper above keeps counting hours and puts the sign at the front, so a negative duration reads sensibly. Note that int() truncates toward zero, so fractions of a second are dropped, not rounded.

The Limits

A timedelta holds at most 999999999 days, and a date only runs from year 1 to year 9999. Overflow raises an error instead of wrapping:

You will rarely hit these by accident, but "no end date" values are a common way to do it: a sentinel such as date.max plus a grace period will overflow. Treat an open-ended interval as None and test for it, rather than inventing a very distant date.

Do Two Intervals Overlap?

Represent an interval as a start and an end, and decide once whether the end is inclusive. The convention that avoids most bugs is half-open: the start is included and the end is not, exactly like range. Then a meeting from 09:00 to 10:00 and another from 10:00 to 11:00 touch but do not collide. Two intervals overlap exactly when each starts before the other ends:

The test needs only two comparisons and no case analysis for "contains", "starts inside" or "ends inside". Both intervals must be the same kind of datetime: Chapter 3 showed that comparing naive and aware values raises an error, and for stored bookings the safe form is aware UTC values (Chapter 4).

Merging and Finding Free Time

Given many intervals, sort them by start and sweep once, extending the last interval whenever the next one begins at or before its end. Merging touching intervals as well as overlapping ones is usually what you want when counting booked time:

The max(out[-1][1], e) matters: a long interval can swallow shorter ones that follow, as the 10:15 to 10:45 entry shows. Dropping the max and using e would shrink the merged span and report phantom free time. Adding up the lengths of the unmerged intervals would also double-count overlaps, which is why you merge first and sum afterwards.

Generating Ranges

Python has no built-in date range, but a generator is three lines. Keep the same half-open rule so that consecutive ranges join without sharing a boundary:

The last two lines show the fence-post trap: the days from 1 to 30 November inclusive number 30, but the difference between the dates is 29. Subtracting two dates gives the distance, not the count of days on the calendar. If your range includes both ends, add one; if it is half-open, the difference is the count. Note that drange uses a fixed step, so over a daylight saving change it should be given naive local times or aware UTC times, as Chapter 5 explained, never aware local times with a "one day" step expected to mean the same wall-clock time.

Bucketing

Bucketing means rounding each timestamp down to the start of its slot (hour, 15 minutes, day) so that you can count or group by slot. Floor division of a timedelta by a timedelta does it neatly when measured from a fixed starting point:

Because every bucket is anchored to the same fixed instant, an event at exactly 10:00:00 lands in the 10:00 bucket and not the 09:00 one, which is the half-open rule again. This works for any step that divides evenly into whole days. Buckets measured in weeks depend on which weekday your anchor falls on (2000-01-01 was a Saturday), and months and years have no fixed length at all, so group those by (d.year, d.month) instead. Also bucket in UTC or in naive local wall-clock time; a one-hour step through an aware local time crosses the daylight saving traps from Chapter 5.

Challenges