pydocket 0.10.0__tar.gz → 0.11.1__tar.gz

pydocket-0.11.1/.github/workflows/claude-code-review.yml

@@ -0,0 +1,40 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  claude-review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@beta
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          model: "claude-opus-4-1-20250805"
+
+          # Direct prompt for automated review (no @claude mention needed)
+          direct_prompt: |
+            Please review this pull request and provide feedback on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security concerns
+            - Test coverage, which must be maintained at 100% for this project
+
+            Be constructive and helpful in your feedback.
+
+          use_sticky_comment: true

pydocket-0.11.1/.github/workflows/claude.yml

@@ -0,0 +1,42 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@beta
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          additional_permissions: |
+            actions: read
+
+          model: "claude-opus-4-1-20250805"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydocket
-Version: 0.10.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.10.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.10.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