pydocket 0.7.0__tar.gz → 0.7.1__tar.gz

{pydocket-0.7.0 → pydocket-0.7.1}/.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ["3.12", "3.13"]
-        redis-version: ["6.2", "7.4"]
+        redis-version: ["6.2", "7.4", "valkey-8.0"]
         redis-py-version: [">=4.6,<5", ">=5"]
 
     steps:
@@ -34,7 +34,7 @@ jobs:
       - name: Run tests
         env:
           REDIS_VERSION: ${{ matrix.redis-version }}
-        run: uv run pytest --cov-branch --cov-report=xml --cov-report=term-missing:skip-covered
+        run: uv run pytest --cov-branch --cov-fail-under=100 --cov-report=xml --cov-report=term-missing:skip-covered
 
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v5

{pydocket-0.7.0 → pydocket-0.7.1}/.github/workflows/publish.yml

@@ -13,8 +13,11 @@ jobs:
     name: Build and publish to PyPI
     runs-on: ubuntu-latest
     needs: ci
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pydocket
     permissions:
-      id-token: write
+      id-token: write  # Required for trusted publishing and PEP 740 attestations
       contents: read
 
     steps:
@@ -31,10 +34,12 @@ jobs:
           cache-dependency-glob: "pyproject.toml"
 
       - name: Install build dependencies
-        run: uv pip install build hatchling hatch-vcs
+        run: uv pip install hatchling hatch-vcs
 
       - name: Build package
         run: uv build
 
-      - name: Publish to PyPI
-        run: uv publish
+      - name: Publish to PyPI with PEP 740 attestations
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

{pydocket-0.7.0 → pydocket-0.7.1}/.gitignore

@@ -1,13 +1,11 @@
-# Python-generated files
-__pycache__/
-*.py[oc]
-build/
-dist/
-wheels/
 *.egg-info
-
-# Virtual environments
-.venv
+*.py[oc]
 .coverage
 .envrc
 .python-version
+.venv
+.worktrees/
+__pycache__/
+build/
+dist/
+wheels/

pydocket-0.7.1/CLAUDE.md

@@ -0,0 +1,127 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**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+
+
+## Development Commands
+
+### Testing
+
+```bash
+# Run full test suite with coverage and parallel execution
+pytest
+
+# Run specific test
+pytest tests/test_docket.py::test_specific_function
+
+```
+
+The project REQUIRES 100% test coverage
+
+### Code Quality
+
+```bash
+# Lint and format code
+ruff check
+ruff format
+
+# Type checking
+pyright
+pyright tests
+
+# Run all pre-commit hooks
+pre-commit run --all-files
+```
+
+### Development Setup
+
+```bash
+# Install development dependencies
+uv sync --group dev
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+### Git Workflow
+
+- This project uses Github for issue tracking
+- This project can use git worktrees under .worktrees/
+
+## Core Architecture
+
+### 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
+  - `strike()`/`restore()`: Conditionally block/unblock tasks
+  - `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
+
+- **`Execution`** (`src/docket/execution.py`): Task execution context with metadata
+
+### Dependencies System (`src/docket/dependencies.py`)
+
+Rich dependency injection supporting:
+
+- Context access: `CurrentDocket`, `CurrentWorker`, `CurrentExecution`
+- Retry strategies: `Retry`, `ExponentialRetry`
+- Special behaviors: `Perpetual` (self-rescheduling), `Timeout`
+- Custom injection: `Depends()`
+- Contextual logging: `TaskLogger`
+
+### Redis Data Model
+
+- **Streams**: `{docket}:stream` (ready tasks), `{docket}:strikes` (commands)
+- **Sorted Sets**: `{docket}:queue` (scheduled tasks), `{docket}:workers` (heartbeats)
+- **Hashes**: `{docket}:{key}` (parked task data)
+- **Sets**: `{docket}:worker-tasks:{worker}` (worker capabilities)
+
+### Task Lifecycle
+
+1. Registration with `Docket.register()` or `@docket.task`
+2. Scheduling: immediate → Redis stream, future → Redis sorted set
+3. Worker processing: scheduler moves due tasks, workers consume via consumer groups
+4. Execution: dependency injection, retry logic, acknowledgment
+
+## Project Structure
+
+### Source Code
+
+- `src/docket/` - Main package
+  - `__init__.py` - Public API exports
+  - `docket.py` - Core Docket class
+  - `worker.py` - Worker implementation
+  - `execution.py` - Task execution context
+  - `dependencies.py` - Dependency injection system
+  - `tasks.py` - Built-in utility tasks
+  - `cli.py` - Command-line interface
+
+### Testing and Examples
+
+- `tests/` - Comprehensive test suite
+- `examples/` - Usage examples
+- `chaos/` - Chaos testing framework
+
+## CLI Usage
+
+```bash
+# Run a worker
+docket worker --url redis://localhost:6379/0 --tasks your.module --concurrency 4
+
+# See all commands
+docket --help
+```

{pydocket-0.7.0 → pydocket-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydocket
-Version: 0.7.0
+Version: 0.7.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.7.0 → pydocket-0.7.1}/src/docket/annotations.py

@@ -2,6 +2,8 @@ import abc
 import inspect
 from typing import Any, Iterable, Mapping, Self
 
+from .instrumentation import CACHE_SIZE
+
 
 class Annotation(abc.ABC):
     _cache: dict[tuple[type[Self], inspect.Signature], Mapping[str, Self]] = {}
@@ -10,6 +12,7 @@ class Annotation(abc.ABC):
     def annotated_parameters(cls, signature: inspect.Signature) -> Mapping[str, Self]:
         key = (cls, signature)
         if key in cls._cache:
+            CACHE_SIZE.set(len(cls._cache), {"cache": "annotation"})
             return cls._cache[key]
 
         annotated: dict[str, Self] = {}
@@ -30,6 +33,7 @@ class Annotation(abc.ABC):
                     annotated[param_name] = arg_type()
 
         cls._cache[key] = annotated
+        CACHE_SIZE.set(len(cls._cache), {"cache": "annotation"})
         return annotated
 
 

{pydocket-0.7.0 → pydocket-0.7.1}/src/docket/cli.py

@@ -358,6 +358,32 @@ def strike(
     asyncio.run(run())
 
 
+@app.command(help="Clear all pending and scheduled tasks from the docket")
+def clear(
+    docket_: Annotated[
+        str,
+        typer.Option(
+            "--docket",
+            help="The name of the docket",
+            envvar="DOCKET_NAME",
+        ),
+    ] = "docket",
+    url: Annotated[
+        str,
+        typer.Option(
+            help="The URL of the Redis server",
+            envvar="DOCKET_URL",
+        ),
+    ] = "redis://localhost:6379/0",
+) -> None:
+    async def run() -> None:
+        async with Docket(name=docket_, url=url) as docket:
+            cleared_count = await docket.clear()
+            print(f"Cleared {cleared_count} tasks from docket '{docket_}'")
+
+    asyncio.run(run())
+
+
 @app.command(help="Restores a task or parameters to the Docket")
 def restore(
     function: Annotated[

{pydocket-0.7.0 → pydocket-0.7.1}/src/docket/dependencies.py

@@ -21,6 +21,7 @@ from typing import (
 
 from .docket import Docket
 from .execution import Execution, TaskFunction, get_signature
+from .instrumentation import CACHE_SIZE
 
 if TYPE_CHECKING:  # pragma: no cover
     from .worker import Worker
@@ -415,6 +416,7 @@ def get_dependency_parameters(
     function: TaskFunction | DependencyFunction[Any],
 ) -> dict[str, Dependency]:
     if function in _parameter_cache:
+        CACHE_SIZE.set(len(_parameter_cache), {"cache": "parameter"})
         return _parameter_cache[function]
 
     dependencies: dict[str, Dependency] = {}
@@ -428,6 +430,7 @@ def get_dependency_parameters(
         dependencies[parameter] = param.default
 
     _parameter_cache[function] = dependencies
+    CACHE_SIZE.set(len(_parameter_cache), {"cache": "parameter"})
     return dependencies
 
 

{pydocket-0.7.0 → pydocket-0.7.1}/src/docket/docket.py

@@ -743,3 +743,46 @@ class Docket:
                 workers.append(WorkerInfo(worker_name, last_seen, task_names))
 
         return workers
+
+    async def clear(self) -> int:
+        """Clear all pending and scheduled tasks from the docket.
+
+        This removes all tasks from the stream (immediate tasks) and queue
+        (scheduled tasks), along with their associated parked data. Running
+        tasks are not affected.
+
+        Returns:
+            The total number of tasks that were cleared.
+        """
+        with tracer.start_as_current_span(
+            "docket.clear",
+            attributes=self.labels(),
+        ):
+            async with self.redis() as redis:
+                async with redis.pipeline() as pipeline:
+                    # Get counts before clearing
+                    pipeline.xlen(self.stream_key)
+                    pipeline.zcard(self.queue_key)
+                    pipeline.zrange(self.queue_key, 0, -1)
+
+                    stream_count: int
+                    queue_count: int
+                    scheduled_keys: list[bytes]
+                    stream_count, queue_count, scheduled_keys = await pipeline.execute()
+
+                    # Clear all data
+                    # Trim stream to 0 messages instead of deleting it to preserve consumer group
+                    if stream_count > 0:
+                        pipeline.xtrim(self.stream_key, maxlen=0, approximate=False)
+                    pipeline.delete(self.queue_key)
+
+                    # Clear parked task data and known task keys
+                    for key_bytes in scheduled_keys:
+                        key = key_bytes.decode()
+                        pipeline.delete(self.parked_task_key(key))
+                        pipeline.delete(self.known_task_key(key))
+
+                    await pipeline.execute()
+
+                    total_cleared = stream_count + queue_count
+                    return total_cleared

{pydocket-0.7.0 → pydocket-0.7.1}/src/docket/execution.py

@@ -19,7 +19,7 @@ import opentelemetry.context
 from opentelemetry import propagate, trace
 
 from .annotations import Logged
-from .instrumentation import message_getter
+from .instrumentation import CACHE_SIZE, message_getter
 
 logger: logging.Logger = logging.getLogger(__name__)
 
@@ -32,10 +32,12 @@ _signature_cache: dict[Callable[..., Any], inspect.Signature] = {}
 
 def get_signature(function: Callable[..., Any]) -> inspect.Signature:
     if function in _signature_cache:
+        CACHE_SIZE.set(len(_signature_cache), {"cache": "signature"})
         return _signature_cache[function]
 
     signature = inspect.signature(function)
     _signature_cache[function] = signature
+    CACHE_SIZE.set(len(_signature_cache), {"cache": "signature"})
     return signature
 
 

{pydocket-0.7.0 → pydocket-0.7.1}/src/docket/instrumentation.py

@@ -117,6 +117,12 @@ SCHEDULE_DEPTH = meter.create_gauge(
     unit="1",
 )
 
+CACHE_SIZE = meter.create_gauge(
+    "docket_cache_size",
+    description="Size of internal docket caches",
+    unit="1",
+)
+
 Message = dict[bytes, bytes]
 
 

{pydocket-0.7.0 → pydocket-0.7.1}/src/docket/worker.py

@@ -15,7 +15,7 @@ from typing import (
 )
 
 from opentelemetry import trace
-from opentelemetry.trace import Tracer
+from opentelemetry.trace import Status, StatusCode, Tracer
 from redis.asyncio import Redis
 from redis.exceptions import ConnectionError, LockError
 
@@ -531,7 +531,7 @@ class Worker:
                 "code.function.name": execution.function.__name__,
             },
             links=execution.incoming_span_links(),
-        ):
+        ) as span:
             try:
                 async with resolved_dependencies(self, execution) as dependencies:
                     # Preemptively reschedule the perpetual task for the future, or clear
@@ -576,6 +576,8 @@ class Worker:
                     duration = log_context["duration"] = time.time() - start
                     TASKS_SUCCEEDED.add(1, counter_labels)
 
+                    span.set_status(Status(StatusCode.OK))
+
                     rescheduled = await self._perpetuate_if_requested(
                         execution, dependencies, timedelta(seconds=duration)
                     )
@@ -584,10 +586,13 @@ class Worker:
                     logger.info(
                         "%s [%s] %s", arrow, ms(duration), call, extra=log_context
                     )
-            except Exception:
+            except Exception as e:
                 duration = log_context["duration"] = time.time() - start
                 TASKS_FAILED.add(1, counter_labels)
 
+                span.record_exception(e)
+                span.set_status(Status(StatusCode.ERROR, str(e)))
+
                 retried = await self._retry_if_requested(execution, dependencies)
                 if not retried:
                     retried = await self._perpetuate_if_requested(

pydocket-0.7.1/tests/cli/test_clear.py

@@ -0,0 +1,253 @@
+import asyncio
+from datetime import datetime, timedelta, timezone
+from unittest.mock import AsyncMock
+
+import pytest
+from typer.testing import CliRunner
+
+from docket.cli import app
+from docket.docket import Docket
+
+
+@pytest.fixture(autouse=True)
+async def empty_docket(docket: Docket):
+    """Ensure that the docket starts empty"""
+    await docket.clear()
+
+
+async def test_clear_command_empty_docket(docket: Docket, runner: CliRunner):
+    """Should clear empty docket and report 0 tasks cleared"""
+    result = await asyncio.get_running_loop().run_in_executor(
+        None,
+        runner.invoke,
+        app,
+        [
+            "clear",
+            "--url",
+            docket.url,
+            "--docket",
+            docket.name,
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    assert "Cleared 0 tasks" in result.output
+
+
+async def test_clear_command_with_immediate_tasks(
+    docket: Docket, runner: CliRunner, the_task: AsyncMock
+):
+    """Should clear immediate tasks and report count"""
+    docket.register(the_task)
+
+    await docket.add(the_task)("arg1")
+    await docket.add(the_task)("arg2")
+    await docket.add(the_task)("arg3")
+
+    result = await asyncio.get_running_loop().run_in_executor(
+        None,
+        runner.invoke,
+        app,
+        [
+            "clear",
+            "--url",
+            docket.url,
+            "--docket",
+            docket.name,
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    assert "Cleared 3 tasks" in result.output
+
+    snapshot = await docket.snapshot()
+    assert len(snapshot.future) == 0
+    assert len(snapshot.running) == 0
+
+
+async def test_clear_command_with_scheduled_tasks(
+    docket: Docket, runner: CliRunner, the_task: AsyncMock
+):
+    """Should clear scheduled tasks and report count"""
+    docket.register(the_task)
+
+    future = datetime.now(timezone.utc) + timedelta(seconds=60)
+    await docket.add(the_task, when=future)("scheduled1")
+    await docket.add(the_task, when=future + timedelta(seconds=1))("scheduled2")
+
+    result = await asyncio.get_running_loop().run_in_executor(
+        None,
+        runner.invoke,
+        app,
+        [
+            "clear",
+            "--url",
+            docket.url,
+            "--docket",
+            docket.name,
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    assert "Cleared 2 tasks" in result.output
+
+    snapshot = await docket.snapshot()
+    assert len(snapshot.future) == 0
+    assert len(snapshot.running) == 0
+
+
+async def test_clear_command_with_mixed_tasks(
+    docket: Docket, runner: CliRunner, the_task: AsyncMock, another_task: AsyncMock
+):
+    """Should clear both immediate and scheduled tasks"""
+    docket.register(the_task)
+    docket.register(another_task)
+
+    future = datetime.now(timezone.utc) + timedelta(seconds=60)
+
+    await docket.add(the_task)("immediate1")
+    await docket.add(another_task)("immediate2")
+    await docket.add(the_task, when=future)("scheduled1")
+    await docket.add(another_task, when=future + timedelta(seconds=1))("scheduled2")
+
+    result = await asyncio.get_running_loop().run_in_executor(
+        None,
+        runner.invoke,
+        app,
+        [
+            "clear",
+            "--url",
+            docket.url,
+            "--docket",
+            docket.name,
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    assert "Cleared 4 tasks" in result.output
+
+    snapshot = await docket.snapshot()
+    assert len(snapshot.future) == 0
+    assert len(snapshot.running) == 0
+
+
+async def test_clear_command_with_keyed_tasks(
+    docket: Docket, runner: CliRunner, the_task: AsyncMock
+):
+    """Should clear tasks with keys"""
+    docket.register(the_task)
+
+    await docket.add(the_task, key="task1")("arg1")
+    await docket.add(the_task, key="task2")("arg2")
+
+    result = await asyncio.get_running_loop().run_in_executor(
+        None,
+        runner.invoke,
+        app,
+        [
+            "clear",
+            "--url",
+            docket.url,
+            "--docket",
+            docket.name,
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    assert "Cleared 2 tasks" in result.output
+
+    snapshot = await docket.snapshot()
+    assert len(snapshot.future) == 0
+
+
+async def test_clear_command_basic_functionality(
+    docket: Docket, runner: CliRunner, the_task: AsyncMock
+):
+    """Should clear tasks via CLI command"""
+    docket.register(the_task)
+
+    # Add some tasks to clear
+    await docket.add(the_task)("task1")
+    future = datetime.now(timezone.utc) + timedelta(seconds=60)
+    await docket.add(the_task, when=future)("scheduled_task")
+
+    result = await asyncio.get_running_loop().run_in_executor(
+        None,
+        runner.invoke,
+        app,
+        [
+            "clear",
+            "--url",
+            docket.url,
+            "--docket",
+            docket.name,
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    assert "Cleared" in result.output
+
+    snapshot_after_clear = await docket.snapshot()
+    assert len(snapshot_after_clear.future) == 0
+
+
+async def test_clear_command_preserves_strikes(
+    docket: Docket, runner: CliRunner, the_task: AsyncMock
+):
+    """Should not affect strikes when clearing"""
+    docket.register(the_task)
+
+    await docket.strike("the_task")
+    await docket.add(the_task)("arg1")
+
+    result = await asyncio.get_running_loop().run_in_executor(
+        None,
+        runner.invoke,
+        app,
+        [
+            "clear",
+            "--url",
+            docket.url,
+            "--docket",
+            docket.name,
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    assert "Cleared" in result.output
+
+    # Strikes should still be in effect - clear doesn't affect strikes
+
+
+async def test_clear_command_with_custom_url(runner: CliRunner):
+    """Should handle custom Redis URL"""
+    result = await asyncio.get_running_loop().run_in_executor(
+        None,
+        runner.invoke,
+        app,
+        [
+            "clear",
+            "--url",
+            "redis://nonexistent:12345/0",
+            "--docket",
+            "test-docket",
+        ],
+    )
+    assert result.exit_code != 0
+    assert result.exit_code != 0
+
+
+async def test_clear_command_with_custom_docket_name(
+    docket: Docket, runner: CliRunner, the_task: AsyncMock
+):
+    """Should handle custom docket name"""
+    docket.register(the_task)
+    await docket.add(the_task)("test")
+
+    result = await asyncio.get_running_loop().run_in_executor(
+        None,
+        runner.invoke,
+        app,
+        [
+            "clear",
+            "--url",
+            docket.url,
+            "--docket",
+            docket.name,
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    assert "Cleared 1 tasks" in result.output

{pydocket-0.7.0 → pydocket-0.7.1}/tests/conftest.py

@@ -90,8 +90,12 @@ def redis_server(testrun_uid: str, worker_id: str) -> Generator[Container, None,
                 s.bind(("", 0))
                 redis_port = s.getsockname()[1]
 
+            image = f"redis:{REDIS_VERSION}"
+            if REDIS_VERSION.startswith("valkey-"):  # pragma: no branch
+                image = f"valkey/valkey:{REDIS_VERSION.replace('valkey-', '')}"  # pragma: no cover
+
             container = client.containers.run(
-                f"redis:{REDIS_VERSION}",
+                image,
                 detach=True,
                 ports={"6379/tcp": redis_port},
                 labels={