pydocket 0.11.0__py3-none-any.whl → 0.11.1__py3-none-any.whl

docket/__init__.py

@@ -8,6 +8,7 @@ from importlib.metadata import version
 
 __version__ = version("pydocket")
 
+from .agenda import Agenda
 from .annotations import Logged
 from .dependencies import (
     ConcurrencyLimit,
@@ -29,6 +30,7 @@ from .worker import Worker
 
 __all__ = [
     "__version__",
+    "Agenda",
     "ConcurrencyLimit",
     "CurrentDocket",
     "CurrentExecution",

docket/agenda.py

@@ -0,0 +1,201 @@
+"""
+Agenda - A collection of tasks that can be scheduled together.
+
+The Agenda class provides a way to collect multiple tasks and then scatter them
+evenly over a time period to avoid overwhelming the system with immediate work.
+"""
+
+import random
+from datetime import datetime, timedelta, timezone
+from typing import Any, Awaitable, Callable, Iterator, ParamSpec, TypeVar, overload
+
+from uuid_extensions import uuid7
+
+from .docket import Docket
+from .execution import Execution, TaskFunction
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class Agenda:
+    """A collection of tasks to be scheduled together on a Docket.
+
+    The Agenda allows you to build up a collection of tasks with their arguments,
+    then schedule them all at once using various timing strategies like scattering.
+
+    Example:
+        >>> agenda = Agenda()
+        >>> agenda.add(process_item)(item1)
+        >>> agenda.add(process_item)(item2)
+        >>> agenda.add(send_email)(email)
+        >>> await agenda.scatter(docket, over=timedelta(minutes=50))
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty Agenda."""
+        self._tasks: list[
+            tuple[TaskFunction | str, tuple[Any, ...], dict[str, Any]]
+        ] = []
+
+    def __len__(self) -> int:
+        """Return the number of tasks in the agenda."""
+        return len(self._tasks)
+
+    def __iter__(
+        self,
+    ) -> Iterator[tuple[TaskFunction | str, tuple[Any, ...], dict[str, Any]]]:
+        """Iterate over tasks in the agenda."""
+        return iter(self._tasks)
+
+    @overload
+    def add(
+        self,
+        function: Callable[P, Awaitable[R]],
+    ) -> Callable[P, None]:
+        """Add a task function to the agenda.
+
+        Args:
+            function: The task function to add.
+
+        Returns:
+            A callable that accepts the task arguments.
+        """
+
+    @overload
+    def add(
+        self,
+        function: str,
+    ) -> Callable[..., None]:
+        """Add a task by name to the agenda.
+
+        Args:
+            function: The name of a registered task.
+
+        Returns:
+            A callable that accepts the task arguments.
+        """
+
+    def add(
+        self,
+        function: Callable[P, Awaitable[R]] | str,
+    ) -> Callable[..., None]:
+        """Add a task to the agenda.
+
+        Args:
+            function: The task function or name to add.
+
+        Returns:
+            A callable that accepts the task arguments and adds them to the agenda.
+        """
+
+        def scheduler(*args: Any, **kwargs: Any) -> None:
+            self._tasks.append((function, args, kwargs))
+
+        return scheduler
+
+    def clear(self) -> None:
+        """Clear all tasks from the agenda."""
+        self._tasks.clear()
+
+    async def scatter(
+        self,
+        docket: Docket,
+        over: timedelta,
+        start: datetime | None = None,
+        jitter: timedelta | None = None,
+    ) -> list[Execution]:
+        """Scatter the tasks in this agenda over a time period.
+
+        Tasks are distributed evenly across the specified time window,
+        optionally with random jitter to prevent thundering herd effects.
+
+        If an error occurs during scheduling, some tasks may have already been
+        scheduled successfully before the failure occurred.
+
+        Args:
+            docket: The Docket to schedule tasks on.
+            over: Time period to scatter tasks over (required).
+            start: When to start scattering from. Defaults to now.
+            jitter: Maximum random offset to add/subtract from each scheduled time.
+
+        Returns:
+            List of Execution objects for the scheduled tasks.
+
+        Raises:
+            KeyError: If any task name is not registered with the docket.
+            ValueError: If any task is stricken or 'over' is not positive.
+        """
+        if over.total_seconds() <= 0:
+            raise ValueError("'over' parameter must be a positive duration")
+
+        if not self._tasks:
+            return []
+
+        if start is None:
+            start = datetime.now(timezone.utc)
+
+        # Calculate even distribution over the time period
+        task_count = len(self._tasks)
+
+        if task_count == 1:
+            # Single task goes in the middle of the window
+            schedule_times = [start + over / 2]
+        else:
+            # Distribute tasks evenly across the window
+            # For n tasks, we want n points from start to start+over inclusive
+            interval = over / (task_count - 1)
+            schedule_times = [start + interval * i for i in range(task_count)]
+
+        # Apply jitter if specified
+        if jitter:
+            jittered_times: list[datetime] = []
+            for schedule_time in schedule_times:
+                # Random offset between -jitter and +jitter
+                offset = timedelta(
+                    seconds=random.uniform(
+                        -jitter.total_seconds(), jitter.total_seconds()
+                    )
+                )
+                # Ensure the jittered time doesn't go before start
+                jittered_time = max(schedule_time + offset, start)
+                jittered_times.append(jittered_time)
+            schedule_times = jittered_times
+
+        # Build all Execution objects first, validating as we go
+        executions: list[Execution] = []
+        for (task_func, args, kwargs), schedule_time in zip(
+            self._tasks, schedule_times
+        ):
+            # Resolve task function if given by name
+            if isinstance(task_func, str):
+                if task_func not in docket.tasks:
+                    raise KeyError(f"Task '{task_func}' is not registered")
+                resolved_func = docket.tasks[task_func]
+            else:
+                # Ensure task is registered
+                if task_func not in docket.tasks.values():
+                    docket.register(task_func)
+                resolved_func = task_func
+
+            # Create execution with unique key
+            key = str(uuid7())
+            execution = Execution(
+                function=resolved_func,
+                args=args,
+                kwargs=kwargs,
+                when=schedule_time,
+                key=key,
+                attempt=1,
+            )
+            executions.append(execution)
+
+        # Schedule all tasks - if any fail, some tasks may have been scheduled
+        for execution in executions:
+            scheduler = docket.add(
+                execution.function, when=execution.when, key=execution.key
+            )
+            # Actually schedule the task - if this fails, earlier tasks remain scheduled
+            await scheduler(*execution.args, **execution.kwargs)
+
+        return executions

docket/docket.py

@@ -455,7 +455,7 @@ class Docket:
                 1,
                 {
                     **self.labels(),
-                    **execution.specific_labels(),
+                    **execution.general_labels(),
                     "docket.where": "docket",
                 },
             )

docket/worker.py

@@ -732,7 +732,7 @@ class Worker:
         execution.attempt += 1
         await self.docket.schedule(execution)
 
-        TASKS_RETRIED.add(1, {**self.labels(), **execution.specific_labels()})
+        TASKS_RETRIED.add(1, {**self.labels(), **execution.general_labels()})
         return True
 
     async def _perpetuate_if_requested(
@@ -758,7 +758,7 @@ class Worker:
         )
 
         if duration is not None:
-            TASKS_PERPETUATED.add(1, {**self.labels(), **execution.specific_labels()})
+            TASKS_PERPETUATED.add(1, {**self.labels(), **execution.general_labels()})
 
         return True
 

{pydocket-0.11.0.dist-info → pydocket-0.11.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydocket
-Version: 0.11.0
+Version: 0.11.1
 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.11.0.dist-info → pydocket-0.11.1.dist-info}/RECORD

@@ -1,16 +1,17 @@
-docket/__init__.py,sha256=onwZzh73tESWoFBukbcW-7gjxoXb-yI7dutRD7tPN6g,915
+docket/__init__.py,sha256=ChJS2JRyruj22Vi504eXrmQNPQ97L_Sj52OJCuhjoeM,956
 docket/__main__.py,sha256=wcCrL4PjG51r5wVKqJhcoJPTLfHW0wNbD31DrUN0MWI,28
+docket/agenda.py,sha256=RqrVkCuWAvwn_q6graCU-lLRQltbJ0QQheJ34T-Gjck,6667
 docket/annotations.py,sha256=wttix9UOeMFMAWXAIJUfUw5GjESJZsACb4YXJCozP7Q,2348
 docket/cli.py,sha256=rTfri2--u4Q5PlXyh7Ub_F5uh3-TtZOWLUp9WY_TvAE,25750
 docket/dependencies.py,sha256=BC0bnt10cr9_S1p5JAP_bnC9RwZkTr9ulPBrxC7eZnA,20247
-docket/docket.py,sha256=jP5uI02in5chQvovRsnPaMhgLff3uiK42A-l3eBh2sE,31241
+docket/docket.py,sha256=NWyulaZYfcNeaqZSJMG54bHqTC5gVggzYFHjpTTY90A,31240
 docket/execution.py,sha256=Lqzgj5EO3v5OD0w__5qBut7WnlEcHZfAYj-BYRdiJf8,15138
 docket/instrumentation.py,sha256=zLYgtuXbNOcotcSlD9pgLVdNp2rPddyxj9JwM3K19Go,5667
 docket/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 docket/tasks.py,sha256=RIlSM2omh-YDwVnCz6M5MtmK8T_m_s1w2OlRRxDUs6A,1437
-docket/worker.py,sha256=hv9ug5WIVAEFPUBCbJ5-lobInwNdMfi7-Ja6fLKdEQ8,35392
-pydocket-0.11.0.dist-info/METADATA,sha256=e34sVFSTXKuWhQ0O60UHfzkGojfAiEMNMkG9pjLGEqo,5419
-pydocket-0.11.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pydocket-0.11.0.dist-info/entry_points.txt,sha256=4WOk1nUlBsUT5O3RyMci2ImuC5XFswuopElYcLHtD5k,47
-pydocket-0.11.0.dist-info/licenses/LICENSE,sha256=YuVWU_ZXO0K_k2FG8xWKe5RGxV24AhJKTvQmKfqXuyk,1087
-pydocket-0.11.0.dist-info/RECORD,,
+docket/worker.py,sha256=P4j9uHXt5KcU5e9S4SmQ9v6OCRFMLjYwbMR9PeRvVXc,35390
+pydocket-0.11.1.dist-info/METADATA,sha256=zl27q0Qf9js2bjyDHEjVWighIGWd4me36FLqY3yt5MI,5419
+pydocket-0.11.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pydocket-0.11.1.dist-info/entry_points.txt,sha256=4WOk1nUlBsUT5O3RyMci2ImuC5XFswuopElYcLHtD5k,47
+pydocket-0.11.1.dist-info/licenses/LICENSE,sha256=YuVWU_ZXO0K_k2FG8xWKe5RGxV24AhJKTvQmKfqXuyk,1087
+pydocket-0.11.1.dist-info/RECORD,,