DST Folds and Ambiguity

## One wall time, two instants A zone that observes daylight saving time changes its UTC offset twice a year. In `America/New_York` the autumn transition falls at 02:00 local on the first Sunday of November: the clock jumps back to 01:00, and every wall time from 01:00:00 to 01:59:59 is lived through twice — once on daylight time (offset `-04:00`) and again an hour later on standard time (offset `-05:00`). Nothing in the six calendar fields of a `datetime` object (year, month, day, hour, minute, second) tells the two passes apart, so `datetime(2025, 11, 2, 1, 30, tzinfo=ZoneInfo("America/New_York"))` is genuinely ambiguous: it names two distinct instants an hour apart. `fold` is the extra field that resolves it. Added in Python 3.6 by PEP 495, it is an integer that is 0 or 1, keyword-only in the constructor, and 0 by default. The rule is chronological, not political: **`fold=0` selects the first (earlier) occurrence of the repeated wall time and `fold=1` selects the second (later) one.** In a northern-hemisphere autumn that makes `fold=0` the daylight reading and `fold=1` the standard reading, but the daylight/standard labels swap in a southern-hemisphere zone while the fold rule does not. Never memorise it as "fold=1 means standard time"; memorise "second time round". ### Who actually reads it The `datetime` class does almost nothing with the flag itself; it passes the object to its `tzinfo`. The three methods that route through the zone — `utcoffset()`, `dst()` and `tzname()` — inspect the fold of the datetime they are asked about, and `zoneinfo.ZoneInfo` implements exactly the PEP 495 rule. Everything layered on those methods therefore becomes fold-sensitive: `astimezone()` to any other zone, `timestamp()`, the offset that `isoformat()` renders, and comparison or subtraction against a datetime carrying a *different* `tzinfo`. Everything else ignores it. Two aware datetimes in the **same** zone that differ only in fold compare equal and hash equal, because PEP 495 deliberately kept intra-zone `==` and `hash()` wall-clock based so that adding the attribute could not silently reshuffle existing dicts and sorted lists. That is the sharpest trap in the feature: a de-duplication pass keyed on equality collapses two events an hour apart, while `timestamp()` on the same pair returns two different numbers. ### How the flag gets set for you You rarely set it by hand — only when interpreting a local wall time that a human or a config file supplied. The library sets it whenever it *derives* a local time from an absolute one: `datetime.fromtimestamp(ts, tz)` and `astimezone(tz)` both mark the result `fold=1` when the instant lands in the second pass. That is what makes a UTC-origin round trip lossless, and it is one more argument for keeping UTC as the storage form and treating local time as a rendering. Arithmetic runs the other way. `timedelta` arithmetic on an aware datetime is wall-clock arithmetic inside the zone: it adds to the naive fields, keeps the same `tzinfo`, and always produces a result with `fold=0`. So noon on the day before the transition plus one day is noon the next day even though 25 real hours elapsed, and adding an interval that lands inside the repeated hour silently picks the first pass. When you need elapsed *real* time, convert both ends to UTC, do the arithmetic there, and convert back. ### A working policy Three rules cover most systems. First, decide the ambiguity policy once, at the edge where a local wall time enters: either reject the input and ask which pass was meant, or default to `fold=0` and **record the choice** alongside the value so the decision is auditable. Second, never let equality do double duty as identity for aware datetimes; compare `timestamp()` values, or convert to UTC first, whenever two candidates could straddle a transition. Third, remember that `fold` only means anything on an aware datetime — a naive datetime carries the attribute but no zone consults it, so setting it on naive data is a no-op that reads like a fix. Detecting the ambiguity is a two-line test: flip the flag and see whether the offset moves. `dt.replace(fold=not dt.fold).utcoffset() != dt.utcoffset()` is true exactly when the wall time sits in a repeated hour or in a spring-forward gap, and a round-trip check separates those two cases. Logging that predicate around the two transition dates is usually enough to find every place a system quietly assumed local times are unique.