pydocket 0.2.1__tar.gz → 0.3.0__tar.gz

{pydocket-0.2.1 → pydocket-0.3.0}/.pre-commit-config.yaml

@@ -24,13 +24,13 @@ repos:
     hooks:
       - id: pyright
         name: pyright (docket package)
-        entry: uv run pyright --verifytypes docket --ignoreexternal
+        entry: pyright --verifytypes docket --ignoreexternal
         language: system
         types: [python]
         pass_filenames: false
       - id: pyright
         name: pyright (source and tests)
-        entry: uv run pyright tests
+        entry: pyright tests
         language: system
         types: [python]
         pass_filenames: false

{pydocket-0.2.1 → pydocket-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydocket
-Version: 0.2.1
+Version: 0.3.0
 Summary: A distributed background task system for Python functions
 Project-URL: Homepage, https://github.com/chrisguidry/docket
 Project-URL: Bug Tracker, https://github.com/chrisguidry/docket/issues

{pydocket-0.2.1 → pydocket-0.3.0}/src/docket/__init__.py

@@ -14,6 +14,7 @@ from .dependencies import (
     CurrentExecution,
     CurrentWorker,
     ExponentialRetry,
+    Perpetual,
     Retry,
     TaskKey,
     TaskLogger,
@@ -34,5 +35,6 @@ __all__ = [
     "Retry",
     "ExponentialRetry",
     "Logged",
+    "Perpetual",
     "__version__",
 ]

{pydocket-0.2.1 → pydocket-0.3.0}/src/docket/dependencies.py

@@ -126,6 +126,34 @@ class ExponentialRetry(Retry):
         return retry
 
 
+class Perpetual(Dependency):
+    single = True
+
+    every: timedelta
+    args: tuple[Any, ...]
+    kwargs: dict[str, Any]
+    cancelled: bool
+
+    def __init__(self, every: timedelta = timedelta(0)) -> None:
+        self.every = every
+        self.cancelled = False
+
+    def __call__(
+        self, docket: Docket, worker: Worker, execution: Execution
+    ) -> "Perpetual":
+        perpetual = Perpetual(every=self.every)
+        perpetual.args = execution.args
+        perpetual.kwargs = execution.kwargs
+        return perpetual
+
+    def cancel(self) -> None:
+        self.cancelled = True
+
+    def perpetuate(self, *args: Any, **kwargs: Any) -> None:
+        self.args = args
+        self.kwargs = kwargs
+
+
 def get_dependency_parameters(
     function: Callable[..., Awaitable[Any]],
 ) -> dict[str, Dependency]:

{pydocket-0.2.1 → pydocket-0.3.0}/src/docket/instrumentation.py

@@ -70,6 +70,12 @@ TASKS_RETRIED = meter.create_counter(
     unit="1",
 )
 
+TASKS_PERPETUATED = meter.create_counter(
+    "docket_tasks_perpetuated",
+    description="How many tasks that have been self-perpetuated",
+    unit="1",
+)
+
 TASK_DURATION = meter.create_histogram(
     "docket_task_duration",
     description="How long tasks take to complete",

{pydocket-0.2.1 → pydocket-0.3.0}/src/docket/worker.py

@@ -36,6 +36,7 @@ from .instrumentation import (
     TASK_PUNCTUALITY,
     TASKS_COMPLETED,
     TASKS_FAILED,
+    TASKS_PERPETUATED,
     TASKS_RETRIED,
     TASKS_RUNNING,
     TASKS_STARTED,
@@ -424,12 +425,20 @@ class Worker:
             TASKS_SUCCEEDED.add(1, counter_labels)
             duration = datetime.now(timezone.utc) - start
             log_context["duration"] = duration.total_seconds()
-            logger.info("%s [%s] %s", "↩", duration, call, extra=log_context)
+            rescheduled = await self._perpetuate_if_requested(
+                execution, dependencies, duration
+            )
+            arrow = "↫" if rescheduled else "↩"
+            logger.info("%s [%s] %s", arrow, duration, call, extra=log_context)
         except Exception:
             TASKS_FAILED.add(1, counter_labels)
             duration = datetime.now(timezone.utc) - start
             log_context["duration"] = duration.total_seconds()
             retried = await self._retry_if_requested(execution, dependencies)
+            if not retried:
+                retried = await self._perpetuate_if_requested(
+                    execution, dependencies, duration
+                )
             arrow = "↫" if retried else "↩"
             logger.exception("%s [%s] %s", arrow, duration, call, extra=log_context)
         finally:
@@ -481,6 +490,34 @@ class Worker:
 
         return False
 
+    async def _perpetuate_if_requested(
+        self, execution: Execution, dependencies: dict[str, Any], duration: timedelta
+    ) -> bool:
+        from .dependencies import Perpetual
+
+        perpetuals = [
+            perpetual
+            for perpetual in dependencies.values()
+            if isinstance(perpetual, Perpetual)
+        ]
+        if not perpetuals:
+            return False
+
+        perpetual = perpetuals[0]
+
+        if perpetual.cancelled:
+            return False
+
+        now = datetime.now(timezone.utc)
+        execution.when = max(now, now + perpetual.every - duration)
+        execution.args = perpetual.args
+        execution.kwargs = perpetual.kwargs
+
+        await self.docket.schedule(execution)
+
+        TASKS_PERPETUATED.add(1, {**self.labels(), **execution.specific_labels()})
+        return True
+
     @property
     def workers_set(self) -> str:
         return self.docket.workers_set

{pydocket-0.2.1 → pydocket-0.3.0}/tests/test_fundamentals.py

@@ -22,6 +22,7 @@ from docket import (
     Execution,
     ExponentialRetry,
     Logged,
+    Perpetual,
     Retry,
     TaskKey,
     TaskLogger,
@@ -854,3 +855,104 @@ async def test_adding_task_with_unbindable_arguments(
         await worker.run_until_finished()
 
     assert "got an unexpected keyword argument 'd'" in caplog.text
+
+
+async def test_perpetual_tasks(docket: Docket, worker: Worker):
+    """Perpetual tasks should reschedule themselves forever"""
+
+    calls = 0
+
+    async def perpetual_task(
+        a: str,
+        b: int,
+        perpetual: Perpetual = Perpetual(every=timedelta(milliseconds=50)),
+    ):
+        assert a == "a"
+        assert b == 2
+
+        assert isinstance(perpetual, Perpetual)
+
+        assert perpetual.every == timedelta(milliseconds=50)
+
+        nonlocal calls
+        calls += 1
+
+    execution = await docket.add(perpetual_task)(a="a", b=2)
+
+    await worker.run_at_most({execution.key: 3})
+
+    assert calls == 3
+
+
+async def test_perpetual_tasks_can_cancel_themselves(docket: Docket, worker: Worker):
+    """A perpetual task can request its own cancellation"""
+    calls = 0
+
+    async def perpetual_task(
+        a: str,
+        b: int,
+        perpetual: Perpetual = Perpetual(every=timedelta(milliseconds=50)),
+    ):
+        assert a == "a"
+        assert b == 2
+
+        assert isinstance(perpetual, Perpetual)
+
+        assert perpetual.every == timedelta(milliseconds=50)
+
+        nonlocal calls
+        calls += 1
+
+        if calls == 3:
+            perpetual.cancel()
+
+    await docket.add(perpetual_task)(a="a", b=2)
+
+    await worker.run_until_finished()
+
+    assert calls == 3
+
+
+async def test_perpetual_tasks_can_change_their_parameters(
+    docket: Docket, worker: Worker
+):
+    """Perpetual tasks may change their parameters each time"""
+    arguments: list[tuple[str, int]] = []
+
+    async def perpetual_task(
+        a: str,
+        b: int,
+        perpetual: Perpetual = Perpetual(every=timedelta(milliseconds=50)),
+    ):
+        arguments.append((a, b))
+        perpetual.perpetuate(a + "a", b=b + 1)
+
+    execution = await docket.add(perpetual_task)(a="a", b=1)
+
+    await worker.run_at_most({execution.key: 3})
+
+    assert len(arguments) == 3
+    assert arguments == [("a", 1), ("aa", 2), ("aaa", 3)]
+
+
+async def test_perpetual_tasks_perpetuate_even_after_errors(
+    docket: Docket, worker: Worker
+):
+    """Perpetual tasks may change their parameters each time"""
+    calls = 0
+
+    async def perpetual_task(
+        a: str,
+        b: int,
+        perpetual: Perpetual = Perpetual(every=timedelta(milliseconds=50)),
+    ):
+        nonlocal calls
+        calls += 1
+
+        raise ValueError("woops!")
+
+    execution = await docket.add(perpetual_task)(a="a", b=1)
+
+    await worker.run_at_most({execution.key: 3})
+
+    assert calls == 3

{pydocket-0.2.1 → pydocket-0.3.0}/tests/test_worker.py

@@ -11,6 +11,7 @@ import redis.exceptions
 from redis.asyncio import Redis
 
 from docket import CurrentWorker, Docket, Worker
+from docket.dependencies import CurrentDocket, Perpetual
 from docket.docket import RedisMessage
 from docket.tasks import standard_tasks
 
@@ -358,3 +359,58 @@ async def test_worker_recovers_from_redis_errors(
         assert worker_info.last_seen > error_time, (
             "Worker should have sent heartbeats after the Redis error"
         )
+
+
+async def test_perpetual_tasks_are_scheduled_close_to_target_time(
+    docket: Docket, worker: Worker
+):
+    """A perpetual task is scheduled as close to the target period as possible"""
+    timestamps: list[datetime] = []
+
+    async def perpetual_task(
+        a: str,
+        b: int,
+        perpetual: Perpetual = Perpetual(every=timedelta(milliseconds=50)),
+    ):
+        timestamps.append(datetime.now(timezone.utc))
+
+        if len(timestamps) % 2 == 0:
+            await asyncio.sleep(0.05)
+
+    await docket.add(perpetual_task, key="my-key")(a="a", b=2)
+
+    await worker.run_at_most({"my-key": 8})
+
+    assert len(timestamps) == 8
+
+    intervals = [next - previous for previous, next in zip(timestamps, timestamps[1:])]
+    total = timedelta(seconds=sum(i.total_seconds() for i in intervals))
+    average = total / len(intervals)
+
+    # even with a variable duration, Docket attempts to schedule them equally
+    assert timedelta(milliseconds=45) <= average <= timedelta(milliseconds=70)
+
+
+async def test_worker_can_exit_from_perpetual_tasks_that_queue_further_tasks(
+    docket: Docket, worker: Worker
+):
+    """A worker can exit if it's processing a perpetual task that queues more tasks"""
+
+    inner_calls = 0
+
+    async def inner_task():
+        nonlocal inner_calls
+        inner_calls += 1
+
+    async def perpetual_task(
+        docket: Docket = CurrentDocket(),
+        perpetual: Perpetual = Perpetual(every=timedelta(milliseconds=50)),
+    ):
+        await docket.add(inner_task)()
+        await docket.add(inner_task)()
+
+    execution = await docket.add(perpetual_task)()
+
+    await worker.run_at_most({execution.key: 3})
+
+    assert inner_calls == 6