pydocket 0.7.0__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.7.0 → 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.7.0 → pydocket-0.13.0b1}/.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.13.0b1}/.gitignore

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

pydocket-0.13.0b1/CLAUDE.md

@@ -0,0 +1,125 @@
+# 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.10+, 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 prek hooks
+uv run prek run --all-files
+```
+
+### Development Setup
+
+```bash
+# Install development dependencies
+uv sync --group dev
+
+# Install prek hooks
+uv run prek 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.13.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydocket
-Version: 0.7.0
+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()
 ```
 
@@ -93,10 +101,12 @@ reference](https://chrisguidry.github.io/docket/api-reference/).
 
 🧩 Fully type-complete and type-aware for your background task functions
 
+💉 Dependency injection like FastAPI, Typer, and FastMCP for reusable resources
+
 ## 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/):
 
@@ -117,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.7.0 → 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()
 ```
 
@@ -57,10 +58,12 @@ reference](https://chrisguidry.github.io/docket/api-reference/).
 
 🧩 Fully type-complete and type-aware for your background task functions
 
+💉 Dependency injection like FastAPI, Typer, and FastMCP for reusable resources
+
 ## 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/):
 
@@ -81,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.7.0 → 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,