feat(cron): add support for custom timezones (#312)

The `croniter` library does support timezone-aware `datetimes`. Since
`_croniter` is initialized with `datetime.now(timezone.utc) `as the base
time, all cron expressions are interpreted in UTC. If you specify `"0 9
* * *"`, that's 9:00 AM UTC, not your system timezone. By providing an
optional timezone argument, we give the user the ability to customize
which timezone should be used so they don't need to manually change the
UTC time twice a year for daylight saving time.

---------

Co-authored-by: Omar Abdelkader <oabdelkader@nvidia.com>

Author: omikader

src/docket/dependencies/_cron.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from datetime import datetime, timezone
+from datetime import datetime, timezone, tzinfo
 from typing import TYPE_CHECKING
 
 from croniter import croniter
@@ -29,6 +29,8 @@ class Cron(Perpetual):
     Example:
 
     ```python
+    from zoneinfo import ZoneInfo
+
     @task
     async def weekly_report(cron: Cron = Cron("0 9 * * 1")) -> None:
         # Runs every Monday at 9:00 AM UTC
@@ -38,17 +40,26 @@ async def weekly_report(cron: Cron = Cron("0 9 * * 1")) -> None:
     async def daily_cleanup(cron: Cron = Cron("@daily")) -> None:
         # Runs every day at midnight UTC
         ...
+
+    @task
+    async def morning_standup(
+        cron: Cron = Cron("0 9 * * 1-5", tz=ZoneInfo("America/Los_Angeles"))
+    ) -> None:
+        # Runs weekdays at 9:00 AM Pacific (handles DST automatically)
+        ...
     ```
     """
 
     expression: str
+    tz: tzinfo
 
     _croniter: croniter[datetime]
 
     def __init__(
         self,
         expression: str,
         automatic: bool = True,
+        tz: tzinfo = timezone.utc,
     ) -> None:
         """
         Args:
@@ -61,14 +72,18 @@ def __init__(
                 startup and continually through the worker's lifespan. This ensures
                 that the task will always be scheduled despite crashes and other
                 adverse conditions. Automatic tasks must not require any arguments.
+            tz: Timezone for interpreting the cron expression. Defaults to UTC.
+                Use `ZoneInfo("America/Los_Angeles")` for Pacific time, etc.
+                This correctly handles daylight saving time transitions.
         """
         super().__init__(automatic=automatic)
         self.expression = expression
-        self._croniter = croniter(expression, datetime.now(timezone.utc), datetime)
+        self.tz = tz
+        self._croniter = croniter(self.expression, datetime.now(self.tz), datetime)
 
     async def __aenter__(self) -> Cron:
         execution = self.execution.get()
-        cron = Cron(expression=self.expression, automatic=self.automatic)
+        cron = Cron(expression=self.expression, automatic=self.automatic, tz=self.tz)
         cron.args = execution.args
         cron.kwargs = execution.kwargs
         return cron

tests/fundamentals/test_cron.py

@@ -2,6 +2,7 @@
 
 from datetime import datetime, timedelta, timezone
 from unittest.mock import patch
+from zoneinfo import ZoneInfo
 
 from croniter import croniter
 
@@ -134,3 +135,24 @@ async def scheduled_task(cron: Cron = Cron("0 9 * * 1")):  # Mondays at 9 AM
     assert len(calls) == 1
     # The task ran at or after the scheduled time, not immediately
     assert calls[0] >= future_time - timedelta(milliseconds=50)
+
+
+async def test_cron_with_timezone(docket: Docket, worker: Worker):
+    """Cron tasks can be scheduled in a specific timezone."""
+    runs = 0
+
+    pacific = ZoneInfo("America/Los_Angeles")
+
+    async def pacific_task(cron: Cron = Cron("0 9 * * *", tz=pacific, automatic=False)):
+        nonlocal runs
+        runs += 1
+
+    with patch.object(
+        croniter,
+        "get_next",
+        return_value=datetime.now(pacific) + timedelta(milliseconds=10),
+    ):
+        execution = await docket.add(pacific_task)()
+        await worker.run_at_most({execution.key: 2})
+
+    assert runs == 2