pydocket 0.11.0__tar.gz → 0.12.0__tar.gz

pydocket-0.12.0/.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.12.0/.github/workflows/ci.yml

@@ -0,0 +1,107 @@
+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: ">=4.6,<5"
+          - 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"
+        exclude:
+          # Python 3.10 + Redis 6.2 + redis-py <5 combination is skipped
+          - python-version: "3.10"
+            backend:
+              name: "Redis 6.2, redis-py <5"
+              redis-version: "6.2"
+              redis-py-version: ">=4.6,<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 --dev --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 }}
+
+  pre-commit:
+    name: Pre-commit 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 --dev
+          uv pip install pip
+
+      - uses: pre-commit/action@v3.0.1
+        with:
+          extra_args: --all-files

{pydocket-0.11.0 → pydocket-0.12.0}/.github/workflows/claude-code-review.yml

@@ -23,7 +23,7 @@ jobs:
         id: claude-review
         uses: anthropics/claude-code-action@beta
         with:
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           model: "claude-opus-4-1-20250805"
 
           # Direct prompt for automated review (no @claude mention needed)

{pydocket-0.11.0 → pydocket-0.12.0}/.github/workflows/claude.yml

@@ -34,7 +34,7 @@ jobs:
         id: claude
         uses: anthropics/claude-code-action@beta
         with:
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
 
           additional_permissions: |
             actions: read

{pydocket-0.11.0 → pydocket-0.12.0}/.gitignore

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

{pydocket-0.11.0 → pydocket-0.12.0}/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
 
@@ -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.11.0 → pydocket-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydocket
-Version: 0.11.0
+Version: 0.12.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
@@ -19,11 +19,15 @@ 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: opentelemetry-api>=1.30.0
 Requires-Dist: opentelemetry-exporter-prometheus>=0.51b0
 Requires-Dist: prometheus-client>=0.21.1
@@ -31,6 +35,7 @@ Requires-Dist: python-json-logger>=3.2.1
 Requires-Dist: redis>=4.6
 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 +74,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 +104,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 +125,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.11.0 → pydocket-0.12.0}/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.11.0 → pydocket-0.12.0}/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.0 → pydocket-0.12.0}/docs/dependencies.md

@@ -160,7 +160,43 @@ Timeouts work alongside retries. If a task times out, it can be retried accordin
 
 ## Custom Dependencies
 
-Create your own dependencies using `Depends()` for reusable resources and patterns:
+Create your own dependencies using `Depends()` for reusable resources and patterns. Dependencies can be either synchronous or asynchronous.
+
+### Synchronous Dependencies
+
+Use sync dependencies for pure computations and in-memory operations:
+
+```python
+from docket import Depends
+
+# In-memory config lookup - no I/O
+def get_config() -> dict:
+    """Access configuration from memory."""
+    return {"api_url": "https://api.example.com", "timeout": 30}
+
+# Pure computation - no I/O
+def build_request_headers(config: dict = Depends(get_config)) -> dict:
+    """Construct headers from config."""
+    return {
+        "User-Agent": "MyApp/1.0",
+        "Timeout": str(config["timeout"])
+    }
+
+async def call_api(
+    headers: dict = Depends(build_request_headers)
+) -> None:
+    # Headers are computed without blocking
+    # Network I/O happens here (async)
+    response = await http_client.get(url, headers=headers)
+```
+
+**Important**: Synchronous dependencies should **NOT** include blocking I/O operations (file access, network calls, database queries, etc.) as it will block the event loop and prevent tasks from being executed. Use async dependencies for any I/O. Sync dependencies are best for:
+- Pure computations
+- In-memory data structure access
+- Configuration lookups from memory
+- Non-blocking transformations
+
+### Asynchronous Dependencies
 
 ```python
 from contextlib import asynccontextmanager
@@ -168,30 +204,78 @@ from docket import Depends
 
 @asynccontextmanager
 async def get_database_connection():
-    """Simple dependency that returns a database connection."""
+    """Async dependency that returns a database connection."""
     conn = await database.connect()
     try:
         yield conn
     finally:
         await conn.close()
 
-@asynccontextmanager
-async def get_redis_client():
-    """Another dependency for Redis operations."""
-    client = redis.Redis(host='localhost', port=6379)
-    try:
-        yield client
-    finally:
-        client.close()
-
 async def process_user_data(
     user_id: int,
-    db=Depends(get_database_connection),
-    cache=Depends(get_redis_client)
+    db=Depends(get_database_connection)
 ) -> None:
-    # Both dependencies are automatically provided and cleaned up
+    # Database connection is automatically provided and cleaned up
     user = await db.fetch_user(user_id)
-    await cache.set(f"user:{user_id}", user.to_json())
+    await db.update_user(user_id, {"last_seen": datetime.now()})
+```
+
+### Synchronous Context Managers
+
+Use sync context managers only for managing in-memory resources or quick non-blocking operations:
+
+```python
+from contextlib import contextmanager
+from docket import Depends
+
+# In-memory resource tracking - no I/O
+@contextmanager
+def track_operation(operation_name: str):
+    """Track operation execution without blocking."""
+    operations_in_progress.add(operation_name)  # In-memory set
+    try:
+        yield operation_name
+    finally:
+        operations_in_progress.remove(operation_name)
+
+async def process_data(
+    tracker=Depends(lambda: track_operation("data_processing"))
+) -> None:
+    # Operation tracked in memory, no blocking
+    await perform_async_work()
+```
+
+### Mixed Sync and Async Dependencies
+
+You can freely mix synchronous and asynchronous dependencies in the same task. Use sync for computations, async for I/O:
+
+```python
+# Sync - in-memory config lookup
+def get_local_config() -> dict:
+    """Access local config from memory - no I/O."""
+    return {"retry_count": 3, "batch_size": 100}
+
+# Async - network I/O
+async def get_remote_config() -> dict:
+    """Fetch remote config via network - requires I/O."""
+    response = await http_client.get("/api/config")
+    return await response.json()
+
+# Sync - pure computation
+def merge_configs(
+    local: dict = Depends(get_local_config),
+    remote: dict = Depends(get_remote_config)
+) -> dict:
+    """Merge configs without blocking - pure computation."""
+    return {**local, **remote}
+
+async def process_batch(
+    config: dict = Depends(merge_configs)
+) -> None:
+    # Config is computed/fetched appropriately
+    # Now do the actual I/O work
+    for i in range(config["batch_size"]):
+        await process_item(i, retries=config["retry_count"])
 ```
 
 ### Nested Dependencies
@@ -220,31 +304,7 @@ async def update_user_profile(
     await user_service.update_profile(user_id, profile_data)
 ```
 
-Dependencies are resolved once per task execution and cached, so if multiple parameters depend on the same resource, only one instance is created.
-
-### Context Manager Dependencies
-
-Dependencies can be async context managers for automatic resource cleanup:
-
-```python
-from contextlib import asynccontextmanager
-
-@asynccontextmanager
-async def get_file_lock(filename: str):
-    """A dependency that provides file locking."""
-    lock = await acquire_file_lock(filename)
-    try:
-        yield lock
-    finally:
-        await release_file_lock(filename)
-
-async def process_shared_file(
-    filename: str,
-    file_lock=Depends(lambda: get_file_lock("shared.txt"))
-) -> None:
-    # File is locked before task starts, unlocked after task completes
-    await process_file_safely(filename)
-```
+Dependencies are resolved once per task execution and cached, so if multiple parameters depend on the same resource, only one instance is created. This caching works across both sync and async dependencies.
 
 ### Dependencies with Built-in Context
 
@@ -337,6 +397,41 @@ If `unreliable_dependency` fails, the task won't execute and the error will be l
 
 ## Dependency Guidelines
 
+### Choose Sync vs Async Appropriately
+
+**Use synchronous dependencies for:**
+- Pure computations (math, string manipulation, data transformations)
+- In-memory data structure access (dicts, lists, sets)
+- Configuration lookups from memory
+- Non-blocking operations that complete instantly
+
+**Use asynchronous dependencies for:**
+- Network I/O (HTTP requests, API calls)
+- File I/O (reading/writing files)
+- Database queries
+- Any operation that involves `await`
+- Resource management requiring async cleanup
+
+```python
+# ✅ Good: Sync for pure computation
+def calculate_batch_size(item_count: int) -> int:
+    return min(item_count, 1000)
+
+# ✅ Good: Async for I/O
+async def fetch_user_data(user_id: int) -> dict:
+    return await api_client.get(f"/users/{user_id}")
+
+# ❌ Bad: Sync with blocking I/O
+def load_config_from_file() -> dict:
+    with open("config.json") as f:  # Blocks the event loop!
+        return json.load(f)
+
+# ✅ Good: Use async for file I/O instead
+async def load_config_from_file() -> dict:
+    async with aiofiles.open("config.json") as f:
+        return json.loads(await f.read())
+```
+
 ### Design for Reusability
 
 Create dependencies that can be used across multiple tasks:

{pydocket-0.11.0 → pydocket-0.12.0}/docs/getting-started.md

@@ -3,7 +3,7 @@
 ## Installation
 
 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/):