pydocket 0.11.1__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.1 → 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.1 → 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.1 → pydocket-0.12.0}/.gitignore

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

{pydocket-0.11.1 → 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.1 → pydocket-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydocket
-Version: 0.11.1
+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.1 → 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.1 → 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.1 → 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/):
 

{pydocket-0.11.1 → pydocket-0.12.0}/docs/testing.md

@@ -2,6 +2,76 @@
 
 Docket includes the utilities you need to test all your background task systems in realistic ways. The ergonomic design supports testing complex workflows with minimal setup.
 
+## Using In-Memory Backend (No Redis Required)
+
+For the fastest tests and simplest setup, Docket supports an in-memory backend using [fakeredis](https://github.com/cunla/fakeredis-py). This is perfect for:
+
+- **CI/CD environments** - No need to spin up Redis containers
+- **Local development** - Test without installing/running Redis
+- **Unit tests** - Fast, isolated tests without external dependencies
+- **Educational environments** - Workshops and tutorials without infrastructure
+
+### Installation
+
+Fakeredis is included as a standard dependency, so no extra installation is needed.
+
+### Usage
+
+Use the `memory://` URL scheme to enable the in-memory backend:
+
+```python
+from docket import Docket
+
+async with Docket(name="test-docket", url="memory://test") as docket:
+    # Use docket normally - all operations are in-memory
+    docket.register(my_task)
+    await docket.add(my_task)("arg")
+```
+
+### Multiple In-Memory Dockets
+
+You can run multiple independent in-memory dockets simultaneously by using different URLs:
+
+```python
+async with (
+    Docket(name="service-a", url="memory://service-a") as docket_a,
+    Docket(name="service-b", url="memory://service-b") as docket_b,
+):
+    # Each docket has its own isolated in-memory data
+    await docket_a.add(task_a)()
+    await docket_b.add(task_b)()
+```
+
+This is useful for testing multi-service scenarios in a single process.
+
+### Pytest Fixture Example
+
+```python
+import pytest
+from docket import Docket, Worker
+from uuid import uuid4
+
+@pytest.fixture
+async def test_docket() -> AsyncGenerator[Docket, None]:
+    """Create a test docket with in-memory backend."""
+    async with Docket(
+        name=f"test-{uuid4()}",
+        url=f"memory://test-{uuid4()}"
+    ) as docket:
+        yield docket
+```
+
+### Limitations
+
+The in-memory backend has some limitations compared to real Redis:
+
+- **Single process only** - Cannot distribute work across multiple processes/machines
+- **Data is ephemeral** - Lost when the process exits
+- **Performance may differ** - Timing-sensitive tests may behave differently
+- **Async polling behavior** - Uses non-blocking reads with manual sleeps for proper asyncio integration
+
+For integration tests or multi-worker scenarios across processes, use a real Redis instance.
+
 ## Testing Tasks as Simple Functions
 
 Often you can test your tasks without running a worker at all! Docket tasks are just Python functions, so you can call them directly and pass test values for dependency parameters: