gh-159715: Fix ZoneInfo TZ rules spanning year boundaries

TZ string lookups only considered rules from the datetime's year, even
when an offset or extended transition time moved a rule into a different
year. Consider neighboring DST periods and join touching periods so that
permanent DST does not introduce a gap or fold at New Year.

Determine folds from actual offset changes. This also avoids marking
times as ambiguous when the first occurrence would have fallen in a gap
at the start of a short DST period. Keep the Python single-year lookup
away from year boundaries when the rule order cannot change between years,
to avoid scanning neighboring periods for ordinary footer lookups.

Add regressions for both implementations, including positive and negative
DST, extended transition hours, and datetime's extreme years.

Author: pganssle

Lib/test/test_zoneinfo/test_zoneinfo.py

@@ -1077,6 +1077,130 @@ def test_tzstr_from_utc(self):
 
                 self.assertEqual(dt_act, dt_utc)
 
+    def test_permanent_dst_year_boundary(self):
+        cases = (
+            ("STD-2DST-1,J1/0,J365/23", 1, -1),
+            ("STD2DST1,J1/0,J365/25", -1, 1),
+        )
+        for tzstr, offset, dst in cases:
+            zi = self.zone_from_tzstr(tzstr)
+            for year in (1, 2, 2019, 2020, 2100, 2400, 9998, 9999):
+                for month, day in ((1, 1), (12, 31)):
+                    for hour in (2, 12, 21, 22, 23):
+                        utc = datetime(year, month, day, hour,
+                                       tzinfo=timezone.utc)
+                        # Keep the expected local time within datetime's range.
+                        if year == 9999 and month == 12 and hour == 23:
+                            continue
+                        with self.subTest(tzstr=tzstr, utc=utc):
+                            local = utc.astimezone(zi)
+                            expected = utc.replace(tzinfo=None)
+                            expected += timedelta(hours=offset)
+                            self.assertEqual(local.replace(tzinfo=None), expected)
+                            self.assertEqual(local.fold, 0)
+                            self.assertEqual(local.tzname(), "DST")
+                            self.assertEqual(local.dst(), timedelta(hours=dst))
+                            self.assertEqual(local.astimezone(timezone.utc), utc)
+                            for fold in (0, 1):
+                                self.assertEqual(
+                                    local.replace(fold=fold).utcoffset(),
+                                    timedelta(hours=offset),
+                                )
+
+    def test_transitions_in_adjacent_year(self):
+        # UTC transition instants are stated explicitly, independently of the
+        # rule evaluation. Cover starts and ends, either sign of DST, and
+        # rules displaced by both UTC offsets and extended transition hours.
+        cases = (
+            ("STD-2DST-3,J1/0,J200/0", datetime(2100, 12, 31, 22), 2, 3),
+            ("STD2DST1,J365/26,J200/0", datetime(2101, 1, 1, 4), -2, -1),
+            ("STD-2DST-1,J1/0,J200/0", datetime(2100, 12, 31, 22), 2, 1),
+            ("STD2DST3,J365/26,J200/0", datetime(2101, 1, 1, 4), -2, -3),
+            ("STD-2DST-3,J200/0,J1/0", datetime(2100, 12, 31, 21), 3, 2),
+            ("STD2DST1,J200/0,J365/26", datetime(2101, 1, 1, 3), -1, -2),
+            ("STD-2DST-1,J200/0,J1/0", datetime(2100, 12, 31, 23), 1, 2),
+            ("STD2DST3,J200/0,J365/26", datetime(2101, 1, 1, 5), -3, -2),
+            ("STD0DST-1,J1/-167,J200/0", datetime(2099, 12, 25, 1), 0, 1),
+            ("STD0DST-1,J200/0,J365/167", datetime(2101, 1, 6, 22), 1, 0),
+            ("STD0DST-1,M12.5.0/167,M6.1.0/0", datetime(1, 1, 6, 23), 0, 1),
+            ("STD0DST-1,J1/-167,J200/0", datetime(9999, 12, 25, 1), 0, 1),
+            ("STD0DST-1,J365/167,J365/166", datetime(2025, 1, 6, 21), 1, 0),
+            ("STD0DST-1,J365/167,J365/166", datetime(2025, 1, 6, 23), 0, 1),
+            ("STD0DST-1,J365/167,J365/166", datetime(1, 1, 6, 21), 1, 0),
+        )
+        for tzstr, transition, old_hours, new_hours in cases:
+            zi = self.zone_from_tzstr(tzstr)
+            old_offset = timedelta(hours=old_hours)
+            new_offset = timedelta(hours=new_hours)
+            for seconds in (-3600, -1, 0, 1, 3599, 3600, 3601):
+                utc = (transition + timedelta(seconds=seconds)).replace(
+                    tzinfo=timezone.utc
+                )
+                offset = old_offset if seconds < 0 else new_offset
+                expected = utc.replace(tzinfo=None) + offset
+                fold = int(new_hours < old_hours and 0 <= seconds < 3600)
+                with self.subTest(tzstr=tzstr, utc=utc):
+                    local = utc.astimezone(zi)
+                    self.assertEqual(local.replace(tzinfo=None), expected)
+                    self.assertEqual(local.utcoffset(), offset)
+                    self.assertEqual(local.fold, fold)
+                    self.assertEqual(local.astimezone(timezone.utc), utc)
+
+            # Local lookups must disambiguate the gap or fold on both sides
+            # of New Year even when it belongs to a different rule year.
+            low = transition + min(old_offset, new_offset)
+            for seconds in (0, 1, 3599):
+                for fold, offset in ((0, old_offset), (1, new_offset)):
+                    local = (low + timedelta(seconds=seconds)).replace(
+                        tzinfo=zi, fold=fold
+                    )
+                    with self.subTest(tzstr=tzstr, local=local, fold=fold):
+                        self.assertEqual(local.utcoffset(), offset)
+
+    def test_rule_order_changes_between_years(self):
+        # In 2021 the first Sunday in March follows the first Monday,
+        # whereas in 2022 it precedes it. The 2021 DST period continues
+        # until March 2022, overlapping the short 2022 period.
+        zi = self.zone_from_tzstr("STD0DST-1,M3.1.0/0,M3.1.1/0")
+        for utc in (
+            datetime(2022, 1, 15, tzinfo=timezone.utc),
+            datetime(2022, 2, 1, tzinfo=timezone.utc),
+            datetime(2022, 3, 6, tzinfo=timezone.utc),
+        ):
+            with self.subTest(utc=utc):
+                local = utc.astimezone(zi)
+                self.assertEqual(local.utcoffset(), ONE_H)
+                self.assertEqual(local.fold, 0)
+                self.assertEqual(local.astimezone(timezone.utc), utc)
+
+    def test_short_dst_period_fold(self):
+        # A short DST period can end before its initial gap has elapsed.
+        # Only local times that actually occur twice should have fold=1.
+        # Exercise short periods near and away from New Year.
+        for day, month, month_day in ((1, 1, 1), (100, 4, 10)):
+            for dst_hours, end in ((1, "1:30"), (-1, "-0:30")):
+                tzstr = f"STD0DST{-dst_hours},J{day}/0,J{day}/{end}"
+                zi = self.zone_from_tzstr(tzstr)
+                transition = datetime(2025, month, month_day,
+                                      tzinfo=timezone.utc)
+                for minute in (-1, 0, 29, 30, 40, 59, 60, 89, 90):
+                    utc = transition + timedelta(minutes=minute)
+                    in_dst = 0 <= minute < 30
+                    offset = timedelta(hours=dst_hours if in_dst else 0)
+                    if dst_hours > 0:
+                        fold = int(60 <= minute < 90)
+                    else:
+                        fold = int(in_dst)
+                    with self.subTest(tzstr=tzstr, utc=utc):
+                        local = utc.astimezone(zi)
+                        self.assertEqual(local.fold, fold)
+                        self.assertEqual(local.utcoffset(), offset)
+                        self.assertEqual(
+                            local.replace(tzinfo=None),
+                            utc.replace(tzinfo=None) + offset,
+                        )
+                        self.assertEqual(local.astimezone(timezone.utc), utc)
+
     def test_extreme_tzstr(self):
         tzstrs = [
             # Extreme offset hour

Lib/zoneinfo/_zoneinfo.py

@@ -462,9 +462,36 @@ def transitions(self, year):
         end = self.end.year_to_epoch(year)
         return start, end
 
+    def _dst_period(self, year):
+        start, end = self.transitions(year)
+        start -= self.std.utcoff.total_seconds()
+        end -= self.dst.utcoff.total_seconds()
+        if end <= start:
+            end = self.end.year_to_epoch(year + 1)
+            end -= self.dst.utcoff.total_seconds()
+        return start, end
+
     def _get_trans_info(self, ts, year, fold):
         """Get the information about the current transition - tti"""
-        start, end = self.transitions(year)
+
+        # Even the largest parsed transition time (<168h), UTC offset
+        # (<25h), and fold (<50h) cannot reach 11 days from a year boundary.
+        year_start = (_post_epoch_days_before_year(year) + 1) * 86400
+        if year_start + 11 * 86400 <= ts < year_start + 354 * 86400:
+            start, end = self.transitions(year)
+            # Each rule's day-of-year can move by up to seven days between
+            # years. Nearby rules can reverse order, allowing a previous
+            # year's southern season to overlap this year's northern one.
+            if abs(end - start - self.dst_diff) > 14 * 86400:
+                if fold == (self.dst_diff >= 0):
+                    end -= self.dst_diff
+                else:
+                    start += self.dst_diff
+                if start < end:
+                    isdst = start <= ts < end
+                else:
+                    isdst = not (end <= ts < start)
+                return self.dst if isdst else self.std
 
         # With fold = 0, the period (denominated in local time) with the
         # smaller offset starts at the end of the gap and ends at the end of
@@ -475,38 +502,57 @@ def _get_trans_info(self, ts, year, fold):
         # the fold and whether DST is positive or negative (rare), and it
         # turns out that this boils down to fold XOR is_positive.
         if fold == (self.dst_diff >= 0):
-            end -= self.dst_diff
-        else:
-            start += self.dst_diff
-
-        if start < end:
-            isdst = start <= ts < end
+            ts -= self.std.utcoff.total_seconds()
         else:
-            isdst = not (end <= ts < start)
-
-        return self.dst if isdst else self.std
+            ts -= self.dst.utcoff.total_seconds()
+
+        # Transition times and UTC offsets can move a rule into an adjacent
+        # year. Taking the union also joins the touching periods used to
+        # represent permanent DST, without introducing a gap or fold.
+        # A southern season with a start shifted into the following January
+        # can still be active two rule years after its start year.
+        for rule_year in (year, year - 1, year + 1, year - 2):
+            start, end = self._dst_period(rule_year)
+            if start <= ts < end:
+                return self.dst
+        return self.std
 
     def _get_trans_info_fromutc(self, ts, year):
-        start, end = self.transitions(year)
-        start -= self.std.utcoff.total_seconds()
-        end -= self.dst.utcoff.total_seconds()
-
-        if start < end:
-            isdst = start <= ts < end
-        else:
-            isdst = not (end <= ts < start)
+        year_start = (_post_epoch_days_before_year(year) + 1) * 86400
+        if year_start + 11 * 86400 <= ts < year_start + 354 * 86400:
+            start, end = self.transitions(year)
+            start -= self.std.utcoff.total_seconds()
+            end -= self.dst.utcoff.total_seconds()
+            if abs(end - start) > 14 * 86400:
+                before = ts - abs(self.dst_diff)
+                if start < end:
+                    isdst = start <= ts < end
+                    wasdst = start <= before < end
+                else:
+                    isdst = not (end <= ts < start)
+                    wasdst = not (end <= before < start)
+                if self.dst_diff > 0:
+                    fold = wasdst and not isdst
+                else:
+                    fold = isdst and not wasdst
+                return self.dst if isdst else self.std, fold
+
+        isdst = False
+        wasdst = False
+        before = ts - abs(self.dst_diff)
+        for rule_year in (year, year - 1, year + 1, year - 2):
+            start, end = self._dst_period(rule_year)
+            isdst |= start <= ts < end
+            wasdst |= start <= before < end
+            if isdst and wasdst:
+                break
 
-        # For positive DST, the ambiguous period is one dst_diff after the end
-        # of DST; for negative DST, the ambiguous period is one dst_diff before
-        # the start of DST.
+        # A fold requires an actual decrease in offset. A nominal transition
+        # at the join between permanent-DST periods does not create one.
         if self.dst_diff > 0:
-            ambig_start = end
-            ambig_end = end + self.dst_diff
+            fold = wasdst and not isdst
         else:
-            ambig_start = start
-            ambig_end = start - self.dst_diff
-
-        fold = ambig_start <= ts < ambig_end
+            fold = isdst and not wasdst
 
         return (self.dst if isdst else self.std, fold)
 

Misc/NEWS.d/next/Library/2026-10-19-12-00-00.gh-issue-159715.year-boundary.rst

@@ -0,0 +1,3 @@
+Fix :class:`zoneinfo.ZoneInfo` handling of TZ string transitions that fall in
+an adjacent year, including permanent daylight saving time and folds near
+New Year.

Modules/_zoneinfo.c

@@ -1481,14 +1481,29 @@ dayrule_new(int julian, int day, int hour, int minute,
     return 0;
 }
 
-/* Calculate the start and end rules for a _tzrule in the given year. */
+/* Calculate a DST period starting in the given rule year, in UTC. */
 static void
-tzrule_transitions(_tzrule *rule, int year, int64_t *start, int64_t *end)
+tzrule_dst_period(_tzrule *rule, int year, int64_t *start, int64_t *end)
 {
     assert(rule->start != NULL);
     assert(rule->end != NULL);
+    // ymd_to_ord assumes positive years. The Gregorian calendar repeats
+    // every 400 years, allowing year 1 lookups to use earlier rules too.
+    int64_t shift = 0;
+    if (year <= 0) {
+        year += 400;
+        shift = 146097LL * 86400;
+    }
     *start = rule->start->year_to_timestamp(rule->start, year);
     *end = rule->end->year_to_timestamp(rule->end, year);
+    *start -= rule->std.utcoff_seconds;
+    *end -= rule->dst.utcoff_seconds;
+    if (*end <= *start) {
+        *end = rule->end->year_to_timestamp(rule->end, year + 1);
+        *end -= rule->dst.utcoff_seconds;
+    }
+    *start -= shift;
+    *end -= shift;
 }
 
 /* Calculate the _ttinfo that applies at a given local time from a _tzrule.
@@ -1506,11 +1521,6 @@ find_tzrule_ttinfo(_tzrule *rule, int64_t ts, unsigned char fold, int year)
         return &(rule->std);
     }
 
-    int64_t start, end;
-    uint8_t isdst;
-
-    tzrule_transitions(rule, year, &start, &end);
-
     // With fold = 0, the period (denominated in local time) with the smaller
     // offset starts at the end of the gap and ends at the end of the fold;
     // with fold = 1, it runs from the start of the gap to the beginning of the
@@ -1520,25 +1530,26 @@ find_tzrule_ttinfo(_tzrule *rule, int64_t ts, unsigned char fold, int year)
     // fold and whether DST is positive or negative (rare), and it turns out
     // that this boils down to fold XOR is_positive.
     if (fold == (rule->dst_diff >= 0)) {
-        end -= rule->dst_diff;
-    }
-    else {
-        start += rule->dst_diff;
-    }
-
-    if (start < end) {
-        isdst = (ts >= start) && (ts < end);
+        ts -= rule->std.utcoff_seconds;
     }
     else {
-        isdst = (ts < end) || (ts >= start);
+        ts -= rule->dst.utcoff_seconds;
     }
 
-    if (isdst) {
-        return &(rule->dst);
-    }
-    else {
-        return &(rule->std);
+    // Transition times and UTC offsets can move a rule into an adjacent
+    // year. The union joins touching permanent-DST periods without a gap
+    // or fold.
+    // A southern season shifted into the following January can still be
+    // active two rule years after its start year.
+    int years[] = {year, year - 1, year + 1, year - 2};
+    for (size_t i = 0; i < 4; i++) {
+        int64_t start, end;
+        tzrule_dst_period(rule, years[i], &start, &end);
+        if (start <= ts && ts < end) {
+            return &(rule->dst);
+        }
     }
+    return &(rule->std);
 }
 
 /* Calculate the ttinfo and fold that applies for a _tzrule at an epoch time.
@@ -1561,33 +1572,23 @@ find_tzrule_ttinfo_fromutc(_tzrule *rule, int64_t ts, int year,
         return &(rule->std);
     }
 
-    int64_t start, end;
-    uint8_t isdst;
-    tzrule_transitions(rule, year, &start, &end);
-    start -= rule->std.utcoff_seconds;
-    end -= rule->dst.utcoff_seconds;
-
-    if (start < end) {
-        isdst = (ts >= start) && (ts < end);
-    }
-    else {
-        isdst = (ts < end) || (ts >= start);
-    }
-
-    // For positive DST, the ambiguous period is one dst_diff after the end of
-    // DST; for negative DST, the ambiguous period is one dst_diff before the
-    // start of DST.
-    int64_t ambig_start, ambig_end;
-    if (rule->dst_diff > 0) {
-        ambig_start = end;
-        ambig_end = end + rule->dst_diff;
-    }
-    else {
-        ambig_start = start;
-        ambig_end = start - rule->dst_diff;
+    uint8_t isdst = 0;
+    uint8_t wasdst = 0;
+    int64_t before = ts - llabs(rule->dst_diff);
+    int years[] = {year, year - 1, year + 1, year - 2};
+    for (size_t i = 0; i < 4; i++) {
+        int64_t start, end;
+        tzrule_dst_period(rule, years[i], &start, &end);
+        isdst |= (start <= ts && ts < end);
+        wasdst |= (start <= before && before < end);
+        if (isdst && wasdst) {
+            break;
+        }
     }
 
-    *fold = (ts >= ambig_start) && (ts < ambig_end);
+    // A nominal transition between permanent-DST periods does not create
+    // a fold: the offset must actually decrease.
+    *fold = rule->dst_diff > 0 ? (wasdst && !isdst) : (isdst && !wasdst);
 
     if (isdst) {
         return &(rule->dst);