Fixed nonexistent DST skip hour in CronTrigger (#1060)

Author: jonasitzmann

docs/versionhistory.rst

@@ -4,6 +4,11 @@ Version history
 To find out how to migrate your application from a previous version of
 APScheduler, see the :doc:`migration section <migration>`.
 
+**UNRELEASED**
+
+- Fixed an issue where ``CronTrigger.next()`` returned a non-existing date on a DST change
+  (`#1059 <https://github.com/agronholm/apscheduler/issues/1059>`_; PR by @jonasitzmann)
+
 **4.0.0a6**
 
 - **BREAKING** Refactored ``AsyncpgEventBroker`` to directly accept a connection string,

src/apscheduler/_utils.py

@@ -99,3 +99,14 @@ def create_repr(instance: object, *attrnames: str, **kwargs) -> str:
 
     rendered_attrs = ", ".join(f"{key}={value!r}" for key, value in kv_pairs)
     return f"{instance.__class__.__name__}({rendered_attrs})"
+
+
+def time_exists(dt: datetime) -> bool:
+    """
+    Determine whether a datetime exists in its time zone.
+
+    :return: ``False`` if the given datetime falls within a gap created by a
+        forward daylight savings shift, otherwise ``True``
+
+    """
+    return dt == datetime.fromtimestamp(dt.timestamp(), dt.tzinfo)

src/apscheduler/triggers/cron/__init__.py

@@ -9,7 +9,7 @@
 from tzlocal import get_localzone
 
 from ..._converters import as_aware_datetime, as_timezone
-from ..._utils import require_state_version, timezone_repr
+from ..._utils import require_state_version, time_exists, timezone_repr
 from ...abc import Trigger
 from .fields import (
     DEFAULT_VALUES,
@@ -232,7 +232,13 @@ def next(self) -> datetime | None:
                 # A valid, but higher than the starting value, was found
                 if field.real:
                     next_time = self._set_field_value(next_time, fieldnum, next_value)
-                    fieldnum += 1
+                    if time_exists(next_time):
+                        fieldnum += 1
+                    else:
+                        # skip non-existent date
+                        next_time, fieldnum = self._increment_field_value(
+                            next_time, fieldnum
+                        )
                 else:
                     next_time, fieldnum = self._increment_field_value(
                         next_time, fieldnum

tests/triggers/test_cron.py

@@ -356,6 +356,7 @@ def test_week_2(timezone, serializer, weekday):
     "trigger_args, start_time, start_time_fold, correct_next_date,"
     "correct_next_date_fold",
     [
+        ({"hour": 2}, datetime(2013, 3, 9, 20), 0, datetime(2013, 3, 11, 2), 0),
         ({"hour": 8}, datetime(2013, 3, 9, 12), 0, datetime(2013, 3, 10, 8), 0),
         ({"hour": 8}, datetime(2013, 11, 2, 12), 0, datetime(2013, 11, 3, 8), 0),
         (
@@ -373,7 +374,13 @@ def test_week_2(timezone, serializer, weekday):
             1,
         ),
     ],
-    ids=["absolute_spring", "absolute_autumn", "interval_spring", "interval_autumn"],
+    ids=[
+        "spring_skip_hour",
+        "absolute_spring",
+        "absolute_autumn",
+        "interval_spring",
+        "interval_autumn",
+    ],
 )
 def test_dst_change(
     trigger_args,