Add a scheduled_at property to task

tasktiger/task.py

@@ -183,6 +183,18 @@ def time_last_queued(self) -> Optional[datetime.datetime]:
         else:
             return datetime.datetime.utcfromtimestamp(timestamp)
 
+    @property
+    def scheduled_at(self) -> Optional[datetime.datetime]:
+        """
+        The timestamp (datetime) of when the task was intended to run — either
+        the `when` value passed to `delay()`, or the time `delay()` was called
+        if no `when` was given. Returns None if the task has never been queued.
+        """
+        timestamp = self._data.get("scheduled_at")
+        if timestamp is None:
+            return None
+        return datetime.datetime.utcfromtimestamp(timestamp)
+
     @property
     def state(self) -> str:
         return self._state
@@ -373,6 +385,8 @@ def delay(
         else:
             state = SCHEDULED
 
+        self._data["scheduled_at"] = ts
+
         # When using ALWAYS_EAGER, make sure we have serialized the task to
         # ensure there are no serialization errors.
         serialized_task = json.dumps(self._data)
@@ -429,6 +443,8 @@ def update_scheduled_time(
                 )
             )
 
+        self._data["scheduled_at"] = ts
+        tiger.connection.set(tiger._key("task", self.id), json.dumps(self._data))
         self._ts = ts
 
     def __repr__(self) -> str:

tests/test_task.py

@@ -1,4 +1,7 @@
+import datetime
+
 import pytest
+from freezefrog import FreezeTime
 
 from tasktiger import Task, TaskNotFound
 
@@ -49,3 +52,51 @@ def some_task():
 
         task = tiger.delay(some_task, max_stored_executions=11)
         assert task.max_stored_executions == 11
+
+
+class TestScheduledAt:
+    FROZEN_NOW = datetime.datetime(2024, 1, 1, 12, 0, 0)
+
+    def test_immediate_task_scheduled_at_equals_queue_time(self, tiger):
+        with FreezeTime(self.FROZEN_NOW):
+            task = tiger.delay(simple_task)
+        assert task.scheduled_at == self.FROZEN_NOW
+
+    def test_future_task_scheduled_at_equals_when(self, tiger):
+        future = datetime.timedelta(minutes=5)
+        with FreezeTime(self.FROZEN_NOW):
+            task = tiger.delay(simple_task, when=future)
+        assert task.scheduled_at == self.FROZEN_NOW + future
+
+    def test_scheduled_at_survives_scheduled_to_queued_transition(self, tiger):
+        future = datetime.timedelta(minutes=5)
+        with FreezeTime(self.FROZEN_NOW):
+            task = tiger.delay(simple_task, when=future)
+        expected = self.FROZEN_NOW + future
+
+        task._move(from_state="scheduled", to_state="queued")
+        reloaded = Task.from_id(tiger, task.queue, "queued", task.id)
+        assert reloaded.scheduled_at == expected
+
+    def test_scheduled_at_persists_after_reload(self, tiger):
+        with FreezeTime(self.FROZEN_NOW):
+            task = tiger.delay(simple_task)
+        reloaded = Task.from_id(tiger, task.queue, "queued", task.id)
+        assert reloaded.scheduled_at == self.FROZEN_NOW
+
+    def test_scheduled_at_none_for_unqueued_task(self, tiger):
+        task = Task(tiger, simple_task)
+        assert task.scheduled_at is None
+
+    def test_update_scheduled_time_updates_scheduled_at(self, tiger):
+        future = datetime.timedelta(minutes=5)
+        later = datetime.timedelta(minutes=10)
+        with FreezeTime(self.FROZEN_NOW):
+            task = tiger.delay(simple_task, when=future)
+        assert task.scheduled_at == self.FROZEN_NOW + future
+
+        new_when = self.FROZEN_NOW + later
+        task.update_scheduled_time(when=new_when)
+
+        reloaded = Task.from_id(tiger, task.queue, "scheduled", task.id)
+        assert reloaded.scheduled_at == new_when