Why does timedelta.seconds mislead after subtracting two datetime objects, and what should you use instead?

## What subtraction actually gives you Subtracting one `datetime` from another produces a `datetime.timedelta`, not a number. A `timedelta` is a *duration* - an amount of elapsed time with no anchor to any calendar date and no time zone. Internally it is exactly three integers, and the constructor normalises whatever you pass into them: - `days` - any integer, positive or negative - `seconds` - always in `0 <= seconds < 86400` - `microseconds` - always in `0 <= microseconds < 1000000` The constructor accepts `weeks`, `days`, `hours`, `minutes`, `seconds`, `milliseconds` and `microseconds`, but it does not *store* them: `timedelta(hours=25)` is stored as `days=1, seconds=3600`. Two `timedelta` objects built from different arguments that describe the same duration are equal and hash the same. ## Why `.seconds` is the classic trap Because `seconds` is capped at one day, it is the *remainder after whole days*, not the duration. A 25-hour outage window reports `seconds == 3600`, and code that logs `gap.seconds` cheerfully reports "1 hour". Nothing raises; the number is simply the wrong number. The second half of the trap is normalisation direction. Python floors towards negative infinity, which keeps `seconds` and `microseconds` non-negative and pushes the sign entirely into `days`: ```python from datetime import datetime gap = datetime(2026, 3, 1, 10) - datetime(2026, 3, 2, 9) # -23 hours print(gap) # -1 day, 1:00:00 print(gap.days, gap.seconds) # -1 3600 print(gap.total_seconds()) # -82800.0 ``` So `.seconds` on a negative duration is positive. Code that branches on `if gap.seconds > 300:` treats "23 hours in the past" as "an hour", and the sign is gone entirely. `str(timedelta)` has the same shape - `'-1 day, 1:00:00'` - which surprises people reading logs, and is why a human-facing duration is usually formatted from `total_seconds()` with `divmod` rather than printed directly. ## `total_seconds()` `total_seconds()` returns `days * 86400 + seconds + microseconds / 10**6` as a **float**, sign included. It is the right default for "how long was this?". Two caveats worth knowing: 1. It is a float. Two durations that differ by a microsecond still compare correctly as `timedelta` objects, but after conversion you are in floating-point territory. For intervals larger than roughly 270 years the float can no longer represent microsecond accuracy - documented, and irrelevant to most services, but the reason the exact form exists. 2. When you want an integer, do not `int(td.total_seconds())` - that truncates towards zero, which is a different rounding than the object's own flooring. Use floor division by a unit `timedelta`, which is exact integer arithmetic on the underlying microseconds: ```python from datetime import timedelta d = timedelta(hours=25, milliseconds=1500) print(d // timedelta(seconds=1)) # 90001 (exact int) print(d / timedelta(minutes=1)) # 1500.025 (float ratio) ``` Dividing a `timedelta` by a `timedelta` gives a plain float ratio; dividing by an int or float gives a `timedelta`; floor-dividing by a `timedelta` gives an int. That trio covers essentially all duration arithmetic without ever converting to raw seconds. ## Prefer comparing durations, not numbers The cleanest fix for most `.seconds` bugs is to stop converting. `timedelta` supports the full ordering and arithmetic set, so a threshold reads better and cannot be misread by unit: ```python from datetime import timedelta STALE_AFTER = timedelta(minutes=15) if gap > STALE_AFTER: # no unit confusion possible refresh() ``` A named `timedelta` constant carries its unit in the constructor keyword, whereas `STALE_AFTER = 900` carries it only in a comment. Deadlines follow the same pattern: `deadline = started_at + timedelta(seconds=30)`, then compare `datetime` objects. ## Other attributes worth knowing - `timedelta.resolution` is one microsecond - the smallest difference the type represents. Sub-microsecond precision does not survive. - `timedelta.min` and `timedelta.max` bound the type at roughly plus or minus 2.7 million years. - `abs(td)` and unary minus work; `td * 2`, `td * 1.5` and `td / 3` all produce `timedelta` results rounded to the nearest microsecond. - Adding a `timedelta` to a `date` gives a `date`; adding one to a `datetime` gives a `datetime`. ## What an interviewer is checking That you know a `timedelta` is a normalised triple rather than a number of seconds, that `.seconds` is a remainder and not a total, that negative durations keep a non-negative `seconds`, and that `total_seconds()` or floor division by a unit `timedelta` is the correct conversion. It is a two-minute answer that reliably separates people who have read the type from people who have only autocompleted it.