pydocket 0.9.2__tar.gz → 0.13.0b1__tar.gz

pydocket-0.13.0b1/.coveragerc-memory

@@ -0,0 +1,10 @@
+# Coverage configuration for memory backend testing
+# CLI tests are skipped with memory:// URLs, so exclude CLI from coverage
+
+[run]
+branch = true
+parallel = true
+omit =
+    src/docket/__main__.py
+    src/docket/cli.py
+    tests/cli/test_*.py

{pydocket-0.9.2 → pydocket-0.13.0b1}/.github/workflows/chaos.yml

@@ -15,6 +15,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Install uv and set Python version
         uses: astral-sh/setup-uv@v5

pydocket-0.13.0b1/.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: Docket CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}, ${{ matrix.backend.name }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        backend:
+          - name: "Redis 6.2, redis-py <5"
+            redis-version: "6.2"
+            redis-py-version: ">=5,<6"
+          - name: "Redis 7.4, redis-py >=5"
+            redis-version: "7.4"
+            redis-py-version: ">=5"
+          - name: "Valkey 8.0, redis-py >=5"
+            redis-version: "valkey-8.0"
+            redis-py-version: ">=5"
+          - name: "Memory (in-memory backend)"
+            redis-version: "memory"
+            redis-py-version: ">=5"
+        include:
+          - python-version: "3.10"
+            cov-threshold: 100
+            pytest-args: ""
+          # Python 3.11 coverage reporting is unstable, so use 98% threshold
+          - python-version: "3.11"
+            cov-threshold: 98
+            pytest-args: ""
+          - python-version: "3.12"
+            cov-threshold: 100
+            pytest-args: ""
+          - python-version: "3.13"
+            cov-threshold: 100
+            pytest-args: ""
+          - python-version: "3.14"
+            cov-threshold: 100
+            pytest-args: ""
+          # Memory backend: CLI tests are skipped via pytest skip markers because
+          # CLI rejects memory:// URLs. Use separate coverage config to exclude CLI.
+          - backend:
+              name: "Memory (in-memory backend)"
+              redis-version: "memory"
+              redis-py-version: ">=5"
+            cov-threshold: 98 # CLI tests are excluded from coverage and some lines are only covered by CLI tests
+            pytest-args: "--cov-config=.coveragerc-memory"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv and set Python version
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Install dependencies
+        run: uv sync --upgrade-package 'redis${{ matrix.backend.redis-py-version }}'
+
+      - name: Run tests
+        env:
+          REDIS_VERSION: ${{ matrix.backend.redis-version }}
+        run: uv run pytest --cov-branch --cov-fail-under=${{ matrix.cov-threshold }} --cov-report=xml --cov-report=term-missing:skip-covered ${{ matrix.pytest-args }}
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          flags: python-${{ matrix.python-version }}
+
+  prek:
+    name: Prek checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv and set Python version
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.10"
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run prek
+        uses: j178/prek-action@v1

pydocket-0.13.0b1/.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:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          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.13.0b1/.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:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+
+          additional_permissions: |
+            actions: read
+
+          model: "claude-opus-4-1-20250805"

{pydocket-0.9.2 → pydocket-0.13.0b1}/.gitignore

@@ -9,3 +9,5 @@ __pycache__/
 build/
 dist/
 wheels/
+
+.coverage.*

{pydocket-0.9.2 → pydocket-0.13.0b1}/CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **Docket** (`pydocket` on PyPI) is a distributed background task system for Python functions with Redis-backed persistence. It enables scheduling both immediate and future work with comprehensive dependency injection, retry mechanisms, and fault tolerance.
 
-**Key Requirements**: Python 3.12+, Redis 6.2+ or Valkey 8.0+
+**Key Requirements**: Python 3.10+, Redis 6.2+ or Valkey 8.0+
 
 ## Development Commands
 
@@ -34,8 +34,8 @@ ruff format
 pyright
 pyright tests
 
-# Run all pre-commit hooks
-pre-commit run --all-files
+# Run all prek hooks
+uv run prek run --all-files
 ```
 
 ### Development Setup
@@ -44,8 +44,8 @@ pre-commit run --all-files
 # Install development dependencies
 uv sync --group dev
 
-# Install pre-commit hooks
-pre-commit install
+# Install prek hooks
+uv run prek install
 ```
 
 ### Git Workflow
@@ -58,7 +58,6 @@ pre-commit install
 ### Key Classes
 
 - **`Docket`** (`src/docket/docket.py`): Central task registry and scheduler
-
   - `add()`: Schedule tasks for execution
   - `replace()`: Replace existing scheduled tasks
   - `cancel()`: Cancel pending tasks
@@ -66,7 +65,6 @@ pre-commit install
   - `snapshot()`: Get current state for observability
 
 - **`Worker`** (`src/docket/worker.py`): Task execution engine
-
   - `run_forever()`/`run_until_finished()`: Main execution loops
   - Handles concurrency, retries, and dependency injection
   - Maintains heartbeat for liveness tracking

{pydocket-0.9.2 → pydocket-0.13.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydocket
-Version: 0.9.2
+Version: 0.13.0b1
 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
@@ -19,18 +19,25 @@ Classifier: Development Status :: 4 - Beta
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
-Requires-Python: >=3.12
+Requires-Python: >=3.10
 Requires-Dist: cloudpickle>=3.1.1
+Requires-Dist: exceptiongroup>=1.2.0; python_version < '3.11'
+Requires-Dist: fakeredis[lua]>=2.32.1
 Requires-Dist: opentelemetry-api>=1.30.0
 Requires-Dist: opentelemetry-exporter-prometheus>=0.51b0
 Requires-Dist: prometheus-client>=0.21.1
+Requires-Dist: py-key-value-aio[memory,redis]>=0.2.8
 Requires-Dist: python-json-logger>=3.2.1
-Requires-Dist: redis>=4.6
+Requires-Dist: redis>=5
 Requires-Dist: rich>=13.9.4
 Requires-Dist: typer>=0.15.1
+Requires-Dist: typing-extensions>=4.12.0
 Requires-Dist: uuid7>=0.1.0
 Description-Content-Type: text/markdown
 
@@ -69,6 +76,7 @@ from docket import Docket, Worker
 
 async with Docket() as docket:
     async with Worker(docket) as worker:
+        worker.register(greet)
         await worker.run_until_finished()
 ```
 
@@ -98,7 +106,7 @@ reference](https://chrisguidry.github.io/docket/api-reference/).
 ## Installing `docket`
 
 Docket is [available on PyPI](https://pypi.org/project/pydocket/) under the package name
-`pydocket`. It targets Python 3.12 or above.
+`pydocket`. It targets Python 3.10 or above.
 
 With [`uv`](https://docs.astral.sh/uv/):
 
@@ -119,6 +127,18 @@ pip install pydocket
 Docket requires a [Redis](http://redis.io/) server with Streams support (which was
 introduced in Redis 5.0.0). Docket is tested with Redis 6 and 7.
 
+For testing without Redis, Docket includes [fakeredis](https://github.com/cunla/fakeredis-py) for in-memory operation:
+
+```python
+from docket import Docket
+
+async with Docket(name="my-docket", url="memory://my-docket") as docket:
+    # Use docket normally - all operations are in-memory
+    ...
+```
+
+See [Testing with Docket](https://chrisguidry.github.io/docket/testing/#using-in-memory-backend-no-redis-required) for more details.
+
 # Hacking on `docket`
 
 We use [`uv`](https://docs.astral.sh/uv/) for project management, so getting set up

{pydocket-0.9.2 → pydocket-0.13.0b1}/README.md

@@ -33,6 +33,7 @@ from docket import Docket, Worker
 
 async with Docket() as docket:
     async with Worker(docket) as worker:
+        worker.register(greet)
         await worker.run_until_finished()
 ```
 
@@ -62,7 +63,7 @@ reference](https://chrisguidry.github.io/docket/api-reference/).
 ## Installing `docket`
 
 Docket is [available on PyPI](https://pypi.org/project/pydocket/) under the package name
-`pydocket`. It targets Python 3.12 or above.
+`pydocket`. It targets Python 3.10 or above.
 
 With [`uv`](https://docs.astral.sh/uv/):
 
@@ -83,6 +84,18 @@ pip install pydocket
 Docket requires a [Redis](http://redis.io/) server with Streams support (which was
 introduced in Redis 5.0.0). Docket is tested with Redis 6 and 7.
 
+For testing without Redis, Docket includes [fakeredis](https://github.com/cunla/fakeredis-py) for in-memory operation:
+
+```python
+from docket import Docket
+
+async with Docket(name="my-docket", url="memory://my-docket") as docket:
+    # Use docket normally - all operations are in-memory
+    ...
+```
+
+See [Testing with Docket](https://chrisguidry.github.io/docket/testing/#using-in-memory-backend-no-redis-required) for more details.
+
 # Hacking on `docket`
 
 We use [`uv`](https://docs.astral.sh/uv/) for project management, so getting set up

{pydocket-0.9.2 → pydocket-0.13.0b1}/chaos/driver.py

@@ -73,7 +73,20 @@ async def main(
     tasks: int = 20000,
     producers: int = 5,
     workers: int = 10,
+    base_version: str | None = None,
 ):
+    if base_version is None:
+        process = await asyncio.create_subprocess_exec(
+            "git",
+            "describe",
+            "--tags",
+            "--abbrev=0",
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+        stdout, _ = await process.communicate()
+        base_version = stdout.decode("utf-8").strip()
+
     async with (
         run_redis("7.4.2") as (redis_url, redis_container),
         Docket(
@@ -105,11 +118,17 @@ async def main(
         )
 
         async def spawn_producer() -> Process:
+            docket_version = base_version if random.random() < 0.5 else "main"
+            base_command = ["uv", "run"]
+            if docket_version != "main":
+                logger.info("Using pydocket %s for producer", docket_version)
+                base_command.extend(["--with", f"pydocket=={docket_version}"])
+            else:
+                logger.info("Using main pydocket for producer")
+
+            command = [*base_command, "-m", "chaos.producer", str(tasks_per_producer)]
             return await asyncio.create_subprocess_exec(
-                *python_entrypoint(),
-                "-m",
-                "chaos.producer",
-                str(tasks_per_producer),
+                *command,
                 env=environment | {"OTEL_SERVICE_NAME": "chaos-producer"},
                 stdout=subprocess.DEVNULL,
                 stderr=subprocess.DEVNULL,
@@ -122,8 +141,16 @@ async def main(
         logger.info("Spawning %d workers...", workers)
 
         async def spawn_worker() -> Process:
-            return await asyncio.create_subprocess_exec(
-                *python_entrypoint(),
+            docket_version = base_version if random.random() < 0.5 else "main"
+            base_command = ["uv", "run"]
+            if docket_version != "main":
+                logger.info("Using pydocket %s for worker", docket_version)
+                base_command.extend(["--with", f"pydocket=={docket_version}"])
+            else:
+                logger.info("Using main pydocket for worker")
+
+            command = [
+                *base_command,
                 "-m",
                 "docket",
                 "worker",
@@ -135,6 +162,9 @@ async def main(
                 "chaos.tasks:chaos_tasks",
                 "--redelivery-timeout",
                 "5s",
+            ]
+            return await asyncio.create_subprocess_exec(
+                *command,
                 env=environment | {"OTEL_SERVICE_NAME": "chaos-worker"},
                 stdout=subprocess.DEVNULL,
                 stderr=subprocess.DEVNULL,

{pydocket-0.9.2 → pydocket-0.13.0b1}/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.