Daylight Saving Traps

Chapter 4 showed that a zone's offset depends on the date. The moments when the offset changes are where most real-world date bugs live. In spring the clocks jump forward and an hour of readings never happens; in autumn they fall back and an hour of readings happens twice. This chapter shows what Python does at those moments, how to detect them, and why "tomorrow" and "24 hours from now" are different questions. Every snippet was run with Python 3.14; the comments show what was printed. In 2026 the New York changes are on 8 March and 1 November, and the London changes on 29 March and 25 October.

The Gap: A Reading That Does Not Exist

On 8 March 2026 New York clocks go from 01:59 straight to 03:00. A reading of 02:30 that day is not on any clock. Python will not stop you from writing it down:

No exception was raised. Python used the offset from before the jump (-05:00) and built an object whose label says 02:30, but the instant it describes is 07:30 UTC, which on a real New York clock reads 03:30. The object lies about its own wall time. A round trip through UTC is the cheap way to find out what the clock really said.

The Fold: A Reading That Happens Twice

On 1 November 2026 New York clocks go from 01:59 back to 01:00. The readings from 01:00 to 01:59 occur twice, an hour apart. Python resolves the ambiguity with the fold attribute: 0 (the default) means the first time the reading occurred, 1 the second.

Two different instants, one hour apart, with identical wall readings. If a user types "01:30" on that night and you never ask which one they meant, you have to pick, and the default silently picks the first. Now the surprising part, which comes from a rule you may not know. When two aware datetimes share the same ZoneInfo object, Python compares and subtracts their wall readings and ignores the offsets:

Chapter 3 said that aware values compare by instant. That is true between different zones (or UTC), but inside one zone the shortcut applies, and at a fold it gives a wrong answer. The safe habit is to convert to UTC before comparing or subtracting anything that might straddle a change.

Detecting the Problem

A reading is ordinary when both fold values give the same offset. If they differ, the reading is special, and the order of the two offsets says which kind. In a repeated hour the first pass is on summer time, so its offset is the larger. In a gap the first (fold=0) offset is the old one, which is the smaller.

A function like this lets a form reject an impossible time with a clear message, or ask the user "first or second 01:30?" instead of guessing.

Adding a Day Is Not Adding 24 Hours

Take noon on Saturday 7 March 2026 in New York, the day before the spring change. timedelta(days=1) and timedelta(hours=24) are the same length, and in an aware datetime they give the same result, because Python adds to the wall reading. That is the trap: the sum is a wall-clock sum, whatever you call the delta.

The first two lines both say "same clock time tomorrow", which is what most people mean by "a day later". The subtraction claims exactly one day passed, but only 23 hours really did. Doing the arithmetic in UTC gives the true moment 24 hours later, which on the New York clock is 13:00. Neither answer is wrong; they answer different questions:

Landing in the Gap on Purpose

Wall-clock arithmetic can walk you into a gap without anyone typing a bad time. A daily job scheduled for 02:30 local time has no valid 02:30 on 8 March. Decide the policy in advance (run at 03:00, run at 03:30, skip the day) rather than letting the library choose. The check from earlier in the chapter tells you which days need the policy:

Here the result is the same as the "shift forward by the gap" policy that many schedulers choose. Whichever policy you pick, write it down, because the next developer will meet the same day.

Challenges