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)

tests/test_task.py

@@ -1,4 +1,7 @@
+import datetime
+
 import pytest
+from freezefrog import FreezeTime
 
 from tasktiger import Task, TaskNotFound
 
@@ -49,3 +52,38 @@ 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