pydocket 0.11.0__tar.gz → 0.11.1__tar.gz

{pydocket-0.11.0 → pydocket-0.11.1}/PKG-INFO

@@ -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 → pydocket-0.11.1}/docs/advanced-patterns.md

@@ -140,6 +140,138 @@ async def process_single_order(order_id: int) -> None:
 
 This pattern separates discovery (finding work) from execution (doing work), allowing for better load distribution and fault isolation. The perpetual task stays lightweight and fast, while the actual work is distributed across many workers.
 
+## Task Scattering with Agenda
+
+For "find-and-flood" workloads, you often want to distribute a batch of tasks over time rather than scheduling them all immediately. The `Agenda` class collects related tasks and scatters them evenly across a time window.
+
+### Basic Scattering
+
+```python
+from datetime import timedelta
+from docket import Agenda, Docket
+
+async def process_item(item_id: int) -> None:
+    await perform_expensive_operation(item_id)
+    await update_database(item_id)
+
+async with Docket() as docket:
+    # Build an agenda of tasks
+    agenda = Agenda()
+    for item_id in range(1, 101):  # 100 items to process
+        agenda.add(process_item)(item_id)
+
+    # Scatter them evenly over 50 minutes to avoid overwhelming the system
+    executions = await agenda.scatter(docket, over=timedelta(minutes=50))
+    print(f"Scheduled {len(executions)} tasks over 50 minutes")
+```
+
+Tasks are distributed evenly across the time window. For 100 tasks over 50 minutes, they'll be scheduled approximately 30 seconds apart.
+
+### Jitter for Thundering Herd Prevention
+
+Add random jitter to prevent multiple processes from scheduling identical work at exactly the same times:
+
+```python
+# Scatter with ±30 second jitter around each scheduled time
+await agenda.scatter(
+    docket,
+    over=timedelta(minutes=50),
+    jitter=timedelta(seconds=30)
+)
+```
+
+### Future Scatter Windows
+
+Schedule the entire batch to start at a specific time in the future:
+
+```python
+from datetime import datetime, timezone
+
+# Start scattering in 2 hours, spread over 30 minutes
+start_time = datetime.now(timezone.utc) + timedelta(hours=2)
+await agenda.scatter(
+    docket,
+    start=start_time,
+    over=timedelta(minutes=30)
+)
+```
+
+### Mixed Task Types
+
+Agendas can contain different types of tasks:
+
+```python
+async def send_email(user_id: str, template: str) -> None:
+    await email_service.send(user_id, template)
+
+async def update_analytics(event_data: dict[str, str]) -> None:
+    await analytics_service.track(event_data)
+
+# Create a mixed agenda
+agenda = Agenda()
+agenda.add(process_item)(item_id=1001)
+agenda.add(send_email)("user123", "welcome")
+agenda.add(update_analytics)({"event": "signup", "user": "user123"})
+agenda.add(process_item)(item_id=1002)
+
+# All tasks will be scattered in the order they were added
+await agenda.scatter(docket, over=timedelta(minutes=10))
+```
+
+### Single Task Positioning
+
+When scattering a single task, it's positioned at the midpoint of the time window:
+
+```python
+agenda = Agenda()
+agenda.add(process_item)(item_id=42)
+
+# This task will be scheduled 5 minutes from now (middle of 10-minute window)
+await agenda.scatter(docket, over=timedelta(minutes=10))
+```
+
+### Agenda Reusability
+
+Agendas can be reused for multiple scatter operations:
+
+```python
+# Create a reusable template
+daily_cleanup_agenda = Agenda()
+daily_cleanup_agenda.add(cleanup_temp_files)()
+daily_cleanup_agenda.add(compress_old_logs)()
+daily_cleanup_agenda.add(update_metrics)()
+
+# Use it multiple times with different timing
+await daily_cleanup_agenda.scatter(docket, over=timedelta(hours=1))
+
+# Later, scatter the same tasks over a different window
+tomorrow = datetime.now(timezone.utc) + timedelta(days=1)
+await daily_cleanup_agenda.scatter(
+    docket,
+    start=tomorrow,
+    over=timedelta(minutes=30)
+)
+```
+
+### Failure Behavior
+
+Keep in mind that, if an error occurs during scheduling, some tasks may have already been scheduled successfully:
+
+```python
+agenda = Agenda()
+agenda.add(valid_task)("arg1")
+agenda.add(valid_task)("arg2")
+agenda.add("nonexistent_task")("arg3")  # This will cause an error
+agenda.add(valid_task)("arg4")
+
+try:
+    await agenda.scatter(docket, over=timedelta(minutes=10))
+except KeyError:
+    # The first two tasks were scheduled successfully
+    # The error prevented the fourth task from being scheduled
+    pass
+```
+
 ## Striking and Restoring Tasks
 
 Striking allows you to temporarily disable tasks without redeploying code. This is invaluable for incident response, gradual rollouts, or handling problematic customers.

pydocket-0.11.1/examples/agenda_scatter.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python
+"""
+Example demonstrating the Agenda scatter functionality for rate-limited workloads.
+
+This example shows a real-world scenario: sending bulk notifications while respecting
+rate limits to avoid overwhelming your notification service or triggering spam filters.
+
+Without scatter: All 26 notifications would try to send immediately, potentially:
+- Overwhelming your notification service
+- Triggering rate limits or spam detection
+- Creating a poor user experience with delayed/failed sends
+
+With scatter: Notifications are distributed evenly over time, respecting limits.
+"""
+
+import asyncio
+import logging
+from datetime import datetime, timedelta, timezone
+
+from docket import Agenda, CurrentExecution, Docket, Execution, Worker
+
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+
+async def send_notification(
+    user: str, message: str, execution: Execution = CurrentExecution()
+) -> None:
+    """Send a notification to a user."""
+    delay = (execution.when - datetime.now(timezone.utc)).total_seconds()
+    if delay > 0.1:
+        logger.info(f"📅 Notification for {user} scheduled {delay:.1f}s from now")
+    else:
+        logger.info(f"📧 Sending to {user}: '{message}'")
+        # Simulate API call to notification service
+        await asyncio.sleep(0.2)
+        logger.info(f"✓ Delivered to {user}")
+
+
+async def main() -> None:
+    """Demonstrate scatter for rate-limited notification sending."""
+
+    async with Docket(name="notification-scatter") as docket:
+        docket.register(send_notification)
+
+        logger.info("=== Bulk Notification Campaign ===")
+        logger.info("Scenario: Alert 26 users about a flash sale")
+        logger.info("Constraint: Notification service allows max 30 messages/minute")
+        logger.info("Strategy: Scatter over 60 seconds (~1 message every 2.3 seconds)")
+        logger.info("")
+
+        # Build the list of users to notify (e.g., from a database query)
+        users = [
+            "alice@example.com",
+            "bob@example.com",
+            "charlie@example.com",
+            "diana@example.com",
+            "eve@example.com",
+            "frank@example.com",
+            "grace@example.com",
+            "henry@example.com",
+            "iris@example.com",
+            "jack@example.com",
+            "kate@example.com",
+            "liam@example.com",
+            "maya@example.com",
+            "noah@example.com",
+            "olivia@example.com",
+            "peter@example.com",
+            "quinn@example.com",
+            "ruby@example.com",
+            "sam@example.com",
+            "tara@example.com",
+            "uma@example.com",
+            "victor@example.com",
+            "wendy@example.com",
+            "xavier@example.com",
+            "yara@example.com",
+            "zoe@example.com",
+        ]
+
+        agenda = Agenda()
+
+        # Queue all notifications
+        logger.info(f"📋 Preparing notifications for {len(users)} users...")
+        for user in users:
+            agenda.add(send_notification)(user, "Flash Sale: 50% off for next hour!")
+
+        # Scatter over 60 seconds to respect rate limit
+        logger.info("🎯 Scattering notifications over 60 seconds...")
+        logger.info("")
+
+        executions = await agenda.scatter(
+            docket,
+            over=timedelta(seconds=60),
+            jitter=timedelta(seconds=0.5),  # Small jitter for natural spacing
+        )
+
+        # Show the distribution preview
+        first_three = executions[:3]
+        last_three = executions[-3:]
+        for i, exec in enumerate(first_three, 1):
+            delay = (exec.when - datetime.now(timezone.utc)).total_seconds()
+            logger.info(f"   Message #{i} scheduled for +{delay:.1f}s")
+        logger.info(f"   ... {len(executions) - 6} more evenly distributed ...")
+        for i, exec in enumerate(last_three, len(executions) - 2):
+            delay = (exec.when - datetime.now(timezone.utc)).total_seconds()
+            logger.info(f"   Message #{i} scheduled for +{delay:.1f}s")
+        logger.info("")
+
+        # Run worker to process the scattered notifications
+        logger.info("🚀 Starting notification sender...")
+        logger.info("   Watch how notifications flow steadily, not in a flood!")
+        logger.info("")
+
+        start_time = datetime.now(timezone.utc)
+        async with Worker(docket, concurrency=2) as worker:
+            await worker.run_until_finished()
+
+        elapsed = (datetime.now(timezone.utc) - start_time).total_seconds()
+        logger.info("")
+        logger.info(f"✅ All {len(users)} notifications sent in {elapsed:.1f} seconds")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{pydocket-0.11.0 → pydocket-0.11.1}/src/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",

pydocket-0.11.1/src/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

{pydocket-0.11.0 → pydocket-0.11.1}/src/docket/docket.py

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

{pydocket-0.11.0 → pydocket-0.11.1}/src/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.1/tests/test_agenda.py

@@ -0,0 +1,404 @@
+from datetime import datetime, timedelta, timezone
+from typing import Any
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from docket import Docket
+from docket.agenda import Agenda
+
+
+@pytest.fixture
+def agenda() -> Agenda:
+    """Create a fresh agenda for testing."""
+    return Agenda()
+
+
+async def test_agenda_creation(agenda: Agenda):
+    """Agenda should be created empty."""
+    assert len(agenda) == 0
+    assert list(agenda) == []
+
+
+async def test_agenda_add_single_task(agenda: Agenda, the_task: AsyncMock):
+    """Should add a single task to the agenda."""
+    agenda.add(the_task)("arg1", kwarg1="value1")
+
+    assert len(agenda) == 1
+    tasks = list(agenda)
+    assert tasks[0][0] == the_task
+    assert tasks[0][1] == ("arg1",)
+    assert tasks[0][2] == {"kwarg1": "value1"}
+
+
+async def test_agenda_add_multiple_tasks(
+    agenda: Agenda, the_task: AsyncMock, another_task: AsyncMock
+):
+    """Should add multiple tasks to the agenda."""
+    agenda.add(the_task)("arg1")
+    agenda.add(another_task)("arg2", key="value")
+    agenda.add(the_task)("arg3")
+
+    assert len(agenda) == 3
+    tasks = list(agenda)
+    assert tasks[0][0] == the_task
+    assert tasks[1][0] == another_task
+    assert tasks[2][0] == the_task
+
+
+async def test_agenda_scatter_basic(
+    docket: Docket, agenda: Agenda, the_task: AsyncMock
+):
+    """Should scatter tasks evenly over the specified timeframe."""
+    docket.register(the_task)
+
+    # Add 3 tasks to scatter over 60 seconds
+    agenda.add(the_task)("task1")
+    agenda.add(the_task)("task2")
+    agenda.add(the_task)("task3")
+
+    start_time = datetime.now(timezone.utc)
+    executions = await agenda.scatter(docket, over=timedelta(seconds=60))
+
+    assert len(executions) == 3
+
+    # Tasks should be scheduled at 0, 30, and 60 seconds
+    expected_times = [
+        start_time,
+        start_time + timedelta(seconds=30),
+        start_time + timedelta(seconds=60),
+    ]
+
+    for execution, expected_time in zip(executions, expected_times):
+        # Allow 1 second tolerance for test execution time
+        assert abs((execution.when - expected_time).total_seconds()) < 1
+
+
+async def test_agenda_scatter_with_start_time(
+    docket: Docket, agenda: Agenda, the_task: AsyncMock
+):
+    """Should scatter tasks starting from a future time."""
+    docket.register(the_task)
+
+    agenda.add(the_task)("task1")
+    agenda.add(the_task)("task2")
+
+    start_time = datetime.now(timezone.utc) + timedelta(minutes=10)
+    executions = await agenda.scatter(
+        docket, start=start_time, over=timedelta(minutes=20)
+    )
+
+    assert len(executions) == 2
+
+    # Tasks should be scheduled at start and start+20min
+    assert abs((executions[0].when - start_time).total_seconds()) < 1
+    assert (
+        abs((executions[1].when - (start_time + timedelta(minutes=20))).total_seconds())
+        < 1
+    )
+
+
+async def test_agenda_scatter_with_jitter(
+    docket: Docket, agenda: Agenda, the_task: AsyncMock
+):
+    """Should add random jitter to scheduled times."""
+    docket.register(the_task)
+
+    # Add many tasks to verify jitter is applied
+    for i in range(5):
+        agenda.add(the_task)(f"task{i}")
+
+    start_time = datetime.now(timezone.utc)
+    executions = await agenda.scatter(
+        docket, over=timedelta(minutes=10), jitter=timedelta(seconds=30)
+    )
+
+    assert len(executions) == 5
+
+    # Calculate expected base times (without jitter)
+    base_times = [start_time + timedelta(minutes=i * 2.5) for i in range(5)]
+
+    # Each task should be within ±30 seconds of its base time
+    for execution, base_time in zip(executions, base_times):
+        diff = abs((execution.when - base_time).total_seconds())
+        assert diff <= 30
+
+
+async def test_agenda_scatter_with_large_jitter(
+    docket: Docket, agenda: Agenda, the_task: AsyncMock
+):
+    """Should ensure jittered times never go before start even with large jitter."""
+    docket.register(the_task)
+
+    # Add tasks that will be scheduled close to start
+    for i in range(3):
+        agenda.add(the_task)(f"task{i}")
+
+    start_time = datetime.now(timezone.utc)
+
+    # Use a very large jitter (5 minutes) on a short window (1 minute)
+    # This could potentially push times before start without our safety check
+    executions = await agenda.scatter(
+        docket, start=start_time, over=timedelta(minutes=1), jitter=timedelta(minutes=5)
+    )
+
+    assert len(executions) == 3
+
+    # All scheduled times should be at or after start_time
+    for execution in executions:
+        assert execution.when >= start_time, (
+            f"Task scheduled at {execution.when} is before start {start_time}"
+        )
+
+
+async def test_agenda_scatter_single_task(
+    docket: Docket, agenda: Agenda, the_task: AsyncMock
+):
+    """Should handle scattering a single task."""
+    docket.register(the_task)
+
+    agenda.add(the_task)("single")
+
+    start_time = datetime.now(timezone.utc)
+    executions = await agenda.scatter(docket, over=timedelta(minutes=10))
+
+    assert len(executions) == 1
+    # Single task should be scheduled in the middle of the window
+    expected_time = start_time + timedelta(minutes=5)
+    assert abs((executions[0].when - expected_time).total_seconds()) < 1
+
+
+async def test_agenda_scatter_empty(docket: Docket, agenda: Agenda):
+    """Should handle scattering an empty agenda."""
+    executions = await agenda.scatter(docket, over=timedelta(minutes=10))
+    assert executions == []
+
+
+async def test_agenda_scatter_heterogeneous_tasks(
+    docket: Docket, agenda: Agenda, the_task: AsyncMock, another_task: AsyncMock
+):
+    """Should scatter different types of tasks."""
+    docket.register(the_task)
+    docket.register(another_task)
+
+    agenda.add(the_task)("task1", key="value1")
+    agenda.add(another_task)(42, flag=True)
+    agenda.add(the_task)("task2")
+    agenda.add(another_task)(99)
+
+    executions = await agenda.scatter(docket, over=timedelta(seconds=90))
+
+    assert len(executions) == 4
+
+    # Verify task types are preserved
+    assert executions[0].function == the_task
+    assert executions[1].function == another_task
+    assert executions[2].function == the_task
+    assert executions[3].function == another_task
+
+    # Verify arguments are preserved
+    assert executions[0].args == ("task1",)
+    assert executions[0].kwargs == {"key": "value1"}
+    assert executions[1].args == (42,)
+    assert executions[1].kwargs == {"flag": True}
+
+
+async def test_agenda_scatter_preserves_order(
+    docket: Docket, agenda: Agenda, the_task: AsyncMock
+):
+    """Should preserve task order when scattering."""
+    docket.register(the_task)
+
+    for i in range(10):
+        agenda.add(the_task)(f"task{i}")
+
+    executions = await agenda.scatter(docket, over=timedelta(minutes=10))
+
+    assert len(executions) == 10
+
+    # Tasks should be scheduled in the same order they were added
+    for i, execution in enumerate(executions):
+        assert execution.args == (f"task{i}",)
+
+    # And times should be monotonically increasing
+    for i in range(1, len(executions)):
+        assert executions[i].when >= executions[i - 1].when
+
+
+async def test_agenda_reusability(docket: Docket, agenda: Agenda, the_task: AsyncMock):
+    """Agenda should be reusable for multiple scatter operations."""
+    docket.register(the_task)
+
+    agenda.add(the_task)("task1")
+    agenda.add(the_task)("task2")
+
+    # First scatter
+    executions1 = await agenda.scatter(docket, over=timedelta(seconds=60))
+    assert len(executions1) == 2
+
+    # Second scatter with different timing
+    start_time = datetime.now(timezone.utc) + timedelta(hours=1)
+    executions2 = await agenda.scatter(
+        docket, start=start_time, over=timedelta(minutes=30)
+    )
+    assert len(executions2) == 2
+
+    # Executions should be different instances with different times
+    assert executions1[0].when != executions2[0].when
+    assert executions1[1].when != executions2[1].when
+
+
+async def test_agenda_scatter_requires_over_parameter(
+    docket: Docket, agenda: Agenda, the_task: AsyncMock
+):
+    """Should raise error if 'over' parameter is not provided."""
+    docket.register(the_task)
+
+    agenda.add(the_task)("task1")
+    agenda.add(the_task)("task2")
+
+    with pytest.raises(
+        TypeError, match="missing 1 required positional argument: 'over'"
+    ):
+        await agenda.scatter(docket)  # type: ignore[call-arg]
+
+
+async def test_agenda_scatter_with_task_by_name(
+    docket: Docket, agenda: Agenda, the_task: AsyncMock
+):
+    """Should support adding tasks by name."""
+    docket.register(the_task)
+
+    # Add task by its registered name
+    agenda.add("the_task")("arg1", key="value")
+
+    executions = await agenda.scatter(docket, over=timedelta(seconds=60))
+
+    assert len(executions) == 1
+    assert executions[0].function == the_task
+    assert executions[0].args == ("arg1",)
+    assert executions[0].kwargs == {"key": "value"}
+
+
+async def test_agenda_scatter_with_non_positive_over_parameter(
+    docket: Docket, agenda: Agenda, the_task: AsyncMock
+):
+    """Should raise ValueError if 'over' parameter is not positive."""
+    docket.register(the_task)
+
+    agenda.add(the_task)("task1")
+    agenda.add(the_task)("task2")
+
+    # Test with zero duration
+    with pytest.raises(
+        ValueError, match="'over' parameter must be a positive duration"
+    ):
+        await agenda.scatter(docket, over=timedelta(seconds=0))
+
+    # Test with negative duration
+    with pytest.raises(
+        ValueError, match="'over' parameter must be a positive duration"
+    ):
+        await agenda.scatter(docket, over=timedelta(seconds=-60))
+
+
+async def test_agenda_scatter_partial_scheduling_behavior(
+    docket: Docket, agenda: Agenda, the_task: AsyncMock, another_task: AsyncMock
+):
+    """Documents the partial scheduling behavior when failures occur."""
+    docket.register(the_task)
+    # Don't register another_task initially
+
+    # Test validation failure - unregistered task fails fast before any scheduling
+    agenda.add(the_task)("task1")
+    agenda.add(the_task)("task2")
+    agenda.add("unregistered_task")("will_fail")  # This will fail validation
+    agenda.add(the_task)("task3")
+
+    # The scatter should fail during validation before scheduling anything
+    with pytest.raises(KeyError, match="Task 'unregistered_task' is not registered"):
+        await agenda.scatter(docket, over=timedelta(seconds=60))
+
+    # Verify no tasks were scheduled (failed during validation)
+    snapshot = await docket.snapshot()
+    assert len(snapshot.future) == 0
+
+    # Test successful case with all registered tasks
+    agenda2 = Agenda()
+    docket.register(another_task)
+
+    agenda2.add(the_task)("task1")
+    agenda2.add(the_task)("task2")
+    agenda2.add(another_task)("task3")
+    agenda2.add(the_task)("task4")
+
+    # All tasks should be scheduled successfully
+    executions = await agenda2.scatter(docket, over=timedelta(seconds=60))
+    assert len(executions) == 4
+
+    # Verify all tasks are in the docket
+    snapshot = await docket.snapshot()
+    assert len(snapshot.future) == 4
+
+    # Clear for next test
+    await docket.clear()
+
+    # Test partial failure during scheduling - earlier tasks remain scheduled
+    agenda3 = Agenda()
+    agenda3.add(the_task)("task1")
+    agenda3.add(the_task)("task2")
+    agenda3.add(the_task)("task3")
+
+    call_count = 0
+    original_add = docket.add
+
+    def failing_add(*args: Any, **kwargs: Any) -> Any:
+        nonlocal call_count
+        call_count += 1
+        if call_count == 2:
+            # Fail on the second task
+            raise RuntimeError("Simulated scheduling failure")
+        return original_add(*args, **kwargs)
+
+    with patch.object(docket, "add", side_effect=failing_add):
+        with pytest.raises(RuntimeError, match="Simulated scheduling failure"):
+            await agenda3.scatter(docket, over=timedelta(seconds=60))
+
+    # The first task should have been scheduled successfully before the failure
+    snapshot = await docket.snapshot()
+    assert len(snapshot.future) == 1  # First task was scheduled
+
+
+async def test_agenda_scatter_auto_registers_unregistered_functions(
+    docket: Docket, agenda: Agenda, the_task: AsyncMock
+):
+    """Should automatically register task functions that aren't already registered."""
+    # the_task is NOT registered yet
+    assert the_task not in docket.tasks.values()
+
+    agenda.add(the_task)("task1")
+    agenda.add(the_task)("task2")
+
+    # scatter should auto-register the task
+    executions = await agenda.scatter(docket, over=timedelta(seconds=30))
+    assert len(executions) == 2
+
+    # Now the task should be registered
+    assert the_task in docket.tasks.values()
+
+    # Verify tasks were scheduled
+    snapshot = await docket.snapshot()
+    assert len(snapshot.future) == 2
+
+
+async def test_agenda_clear(agenda: Agenda, the_task: AsyncMock):
+    """Should support clearing all tasks from agenda."""
+    agenda.add(the_task)("task1")
+    agenda.add(the_task)("task2")
+
+    assert len(agenda) == 2
+
+    agenda.clear()
+
+    assert len(agenda) == 0
+    assert list(agenda) == []

{pydocket-0.11.0 → pydocket-0.11.1}/tests/test_instrumentation.py

@@ -13,7 +13,7 @@ from opentelemetry.sdk.trace import Span, TracerProvider
 from opentelemetry.trace import StatusCode
 
 from docket import Docket, Worker
-from docket.dependencies import Retry
+from docket.dependencies import Perpetual, Retry
 from docket.instrumentation import (
     healthcheck_server,
     message_getter,
@@ -376,6 +376,14 @@ def TASKS_RETRIED(monkeypatch: pytest.MonkeyPatch) -> Mock:
     return mock
 
 
+@pytest.fixture
+def TASKS_PERPETUATED(monkeypatch: pytest.MonkeyPatch) -> Mock:
+    """Mock for the TASKS_PERPETUATED counter."""
+    mock = Mock(spec=Counter.add)
+    monkeypatch.setattr("docket.instrumentation.TASKS_PERPETUATED.add", mock)
+    return mock
+
+
 @pytest.fixture
 def TASKS_REDELIVERED(monkeypatch: pytest.MonkeyPatch) -> Mock:
     """Mock for the TASKS_REDELIVERED counter."""
@@ -492,6 +500,58 @@ async def test_exhausted_retried_task_increments_retry_counter(
     TASKS_REDELIVERED.assert_not_called()
 
 
+async def test_retried_task_metric_uses_bounded_labels(
+    docket: Docket,
+    worker: Worker,
+    worker_labels: dict[str, str],
+    TASKS_RETRIED: Mock,
+):
+    """TASKS_RETRIED should only use bounded-cardinality labels (not task keys)."""
+
+    async def the_task(retry: Retry = Retry(attempts=2)):
+        raise ValueError("Always fails")
+
+    await docket.add(the_task)()
+    await worker.run_until_finished()
+
+    assert TASKS_RETRIED.call_count == 1
+    call_labels = TASKS_RETRIED.call_args.args[1]
+
+    assert "docket.name" in call_labels
+    assert "docket.worker" in call_labels
+    assert "docket.task" in call_labels
+    assert "docket.key" not in call_labels
+    assert "docket.when" not in call_labels
+    assert "docket.attempt" not in call_labels
+
+
+async def test_perpetuated_task_metric_uses_bounded_labels(
+    docket: Docket,
+    worker: Worker,
+    worker_labels: dict[str, str],
+    TASKS_PERPETUATED: Mock,
+):
+    """TASKS_PERPETUATED should only use bounded-cardinality labels (not task keys)."""
+
+    async def the_task(
+        perpetual: Perpetual = Perpetual(every=timedelta(milliseconds=50)),
+    ):
+        pass
+
+    execution = await docket.add(the_task)()
+    await worker.run_at_most({execution.key: 2})
+
+    assert TASKS_PERPETUATED.call_count >= 1
+    call_labels = TASKS_PERPETUATED.call_args.args[1]
+
+    assert "docket.name" in call_labels
+    assert "docket.worker" in call_labels
+    assert "docket.task" in call_labels
+    assert "docket.key" not in call_labels
+    assert "docket.when" not in call_labels
+    assert "docket.attempt" not in call_labels
+
+
 async def test_redelivered_tasks_increment_redelivered_counter(
     docket: Docket,
     worker_labels: dict[str, str],