pydocket 0.26.0__tar.gz → 0.26.2__tar.gz

{pydocket-0.26.0 → pydocket-0.26.2}/.coveragerc-core

@@ -10,11 +10,13 @@ omit =
     **/conftest.py
     tests/_key_leak_checker.py
     tests/_container.py
+    tests/_rotating_provider.py
     tests/sitecustomize.py
     tests/cli/*.py
     # real-Redis-only; skips on the memory and cluster legs
     tests/test_socket_timeout.py
     tests/test_pubsub_resp_version.py
+    tests/test_credential_rotation.py
 
 [report]
 exclude_also =

{pydocket-0.26.0 → pydocket-0.26.2}/.gitignore

@@ -14,3 +14,7 @@ wheels/
 .coverage.*
 .loq_cache
 .claude/scheduled_tasks.lock
+coverage.xml
+junit.xml
+target/
+target-*/

pydocket-0.26.2/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+# The root config's hooks, ruff among them, also cover this directory.
+repos:
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright (docket package)
+        entry: uv run pyright --verifytypes docket --ignoreexternal
+        language: system
+        types: [python]
+        pass_filenames: false
+      - id: pyright
+        name: pyright (tests and conformance agent)
+        entry: uv run pyright tests conformance-agent
+        language: system
+        types: [python]
+        pass_filenames: false

{pydocket-0.26.0 → pydocket-0.26.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pydocket
-Version: 0.26.0
+Version: 0.26.2
 Summary: A distributed background task system for Python functions
 Project-URL: Homepage, https://docket.lol/
 Project-URL: Documentation, https://docket.lol/en/latest/
@@ -36,7 +36,7 @@ Requires-Dist: opentelemetry-api>=1.33.0
 Requires-Dist: prometheus-client>=0.21.1
 Requires-Dist: py-key-value-aio[memory,redis]>=0.3.0
 Requires-Dist: python-json-logger>=2.0.7
-Requires-Dist: redis>=5
+Requires-Dist: redis>=6
 Requires-Dist: rich>=13.9.4
 Requires-Dist: taskgroup>=0.2.2; python_version < '3.11'
 Requires-Dist: typer>=0.15.1
@@ -52,7 +52,7 @@ on the scheduling of future work as seamlessly and efficiently as immediate work
 
 [![PyPI - Version](https://img.shields.io/pypi/v/pydocket)](https://pypi.org/project/pydocket/)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pydocket)](https://pypi.org/project/pydocket/)
-[![GitHub main checks](https://img.shields.io/github/check-runs/chrisguidry/docket/main)](https://github.com/chrisguidry/docket/actions/workflows/ci.yml)
+[![GitHub main checks](https://img.shields.io/github/check-runs/chrisguidry/docket/main)](https://github.com/chrisguidry/docket/actions)
 [![Codecov](https://img.shields.io/codecov/c/github/chrisguidry/docket)](https://app.codecov.io/gh/chrisguidry/docket)
 [![PyPI - License](https://img.shields.io/pypi/l/pydocket)](https://github.com/chrisguidry/docket/blob/main/LICENSE)
 [![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://docket.lol/)
@@ -130,11 +130,11 @@ With `pip`:
 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:
+Docket requires [Redis](https://redis.io/) 6.2 or later, or
+[Valkey](https://valkey.io/) 8.0 or later. Docket is tested with:
 
-- Redis 6.2, 7.4, and 8.6 (standalone and cluster modes)
-- [Valkey](https://valkey.io/) 8.1
+- Redis 6.2 and 8.10, and Redis 8.10 in cluster mode
+- Valkey 8.0 and 9.1
 - In-memory backend via [burner-redis](https://github.com/prefectlabs/burner-redis) for testing
 
 For testing without Redis, use the in-memory backend:
@@ -151,17 +151,14 @@ See [Testing with Docket](https://docket.lol/en/latest/testing/#using-in-memory-
 
 # Hacking on `docket`
 
-We use [`uv`](https://docs.astral.sh/uv/) for project management, so getting set up
-should be as simple as cloning the repo and running:
+We use [`uv`](https://docs.astral.sh/uv/) for project management.  The
+repository is a uv workspace, and the Python package lives in its `python/`
+directory.  From a clone of the repository:
 
 ```bash
 uv sync
-```
-
-The to run the test suite:
-
-```bash
-pytest
+cd python
+uv run pytest
 ```
 
 We aim to maintain 100% test coverage, which is required for all PRs to `docket`. We
@@ -170,7 +167,7 @@ begins with testing all the dusty branches and corners. This will give us the
 confidence to upgrade dependencies quickly and to adapt to new versions of Redis over
 time.
 
-To work on the documentation locally:
+To work on the documentation locally, from the repository root:
 
 ```bash
 uv sync

{pydocket-0.26.0 → pydocket-0.26.2}/README.md

@@ -3,7 +3,7 @@ on the scheduling of future work as seamlessly and efficiently as immediate work
 
 [![PyPI - Version](https://img.shields.io/pypi/v/pydocket)](https://pypi.org/project/pydocket/)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pydocket)](https://pypi.org/project/pydocket/)
-[![GitHub main checks](https://img.shields.io/github/check-runs/chrisguidry/docket/main)](https://github.com/chrisguidry/docket/actions/workflows/ci.yml)
+[![GitHub main checks](https://img.shields.io/github/check-runs/chrisguidry/docket/main)](https://github.com/chrisguidry/docket/actions)
 [![Codecov](https://img.shields.io/codecov/c/github/chrisguidry/docket)](https://app.codecov.io/gh/chrisguidry/docket)
 [![PyPI - License](https://img.shields.io/pypi/l/pydocket)](https://github.com/chrisguidry/docket/blob/main/LICENSE)
 [![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://docket.lol/)
@@ -81,11 +81,11 @@ With `pip`:
 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:
+Docket requires [Redis](https://redis.io/) 6.2 or later, or
+[Valkey](https://valkey.io/) 8.0 or later. Docket is tested with:
 
-- Redis 6.2, 7.4, and 8.6 (standalone and cluster modes)
-- [Valkey](https://valkey.io/) 8.1
+- Redis 6.2 and 8.10, and Redis 8.10 in cluster mode
+- Valkey 8.0 and 9.1
 - In-memory backend via [burner-redis](https://github.com/prefectlabs/burner-redis) for testing
 
 For testing without Redis, use the in-memory backend:
@@ -102,17 +102,14 @@ See [Testing with Docket](https://docket.lol/en/latest/testing/#using-in-memory-
 
 # Hacking on `docket`
 
-We use [`uv`](https://docs.astral.sh/uv/) for project management, so getting set up
-should be as simple as cloning the repo and running:
+We use [`uv`](https://docs.astral.sh/uv/) for project management.  The
+repository is a uv workspace, and the Python package lives in its `python/`
+directory.  From a clone of the repository:
 
 ```bash
 uv sync
-```
-
-The to run the test suite:
-
-```bash
-pytest
+cd python
+uv run pytest
 ```
 
 We aim to maintain 100% test coverage, which is required for all PRs to `docket`. We
@@ -121,7 +118,7 @@ begins with testing all the dusty branches and corners. This will give us the
 confidence to upgrade dependencies quickly and to adapt to new versions of Redis over
 time.
 
-To work on the documentation locally:
+To work on the documentation locally, from the repository root:
 
 ```bash
 uv sync

{pydocket-0.26.0 → pydocket-0.26.2}/pyproject.toml

@@ -32,7 +32,7 @@ dependencies = [
     "prometheus-client>=0.21.1",
     "py-key-value-aio[memory,redis]>=0.3.0",
     "python-json-logger>=2.0.7",
-    "redis>=5",
+    "redis>=6",
     "rich>=13.9.4",
     "typer>=0.15.1",
     "typing_extensions>=4.12.0",
@@ -47,12 +47,9 @@ metrics = [
 
 [dependency-groups]
 dev = [
-    "codespell>=2.4.1",
     "docker>=7.1.0",
     # Security: urllib3 >=2.6.3 fixes decompression bomb vulnerabilities
     "urllib3>=2.6.3",
-    "ipython>=8.0.0",
-    "loq>=0.1.0a3",
     "opentelemetry-distro>=0.60b0",
     "opentelemetry-exporter-otlp>=1.33.0",
     "opentelemetry-exporter-prometheus>=0.60b0",
@@ -60,7 +57,6 @@ dev = [
     "opentelemetry-instrumentation-logging>=0.60b0",
     "opentelemetry-instrumentation-redis>=0.60b0",
     "opentelemetry-sdk>=1.33.0",
-    "prek>=0.3.1",
     "pyright>=1.1.408",
     "pytest>=9.0.2",
     "pytest-asyncio>=0.24.0",
@@ -71,16 +67,6 @@ dev = [
     "pytest-timeout>=2.4.0",
     "pytest-xdist>=3.6.1",
     "ruff>=0.14.14",
-    "zensical>=0.0.32",
-    "mkdocstrings>=1.0.2",
-    "mkdocstrings-python>=2.0.1",
-]
-examples = [
-    "fastapi>=0.120.0",
-    "pydantic>=2.12.5",
-    # Security: starlette >=0.49.1 fixes session middleware vulnerability
-    "starlette>=0.49.1",
-    "uvicorn>=0.40.0",
 ]
 
 [project.scripts]
@@ -94,6 +80,11 @@ docket = "docket.__main__:app"
 
 [tool.hatch.version]
 source = "vcs"
+# Releases before the monorepo are tagged bare (0.26.0), and later ones
+# python/v0.27.0.  Matching only these keeps another language's tag, like
+# rust/v0.1.0, out of pydocket's version.
+tag-pattern = "^(?:python/v)?(?P<version>\\d+\\.\\d+\\.\\d+.*)$"
+raw-options = { root = "..", scm = { git = { describe_command = "git describe --dirty --tags --long --match python/v* --match [0-9]*" } } }
 
 [tool.hatch.metadata]
 allow-direct-references = true
@@ -102,8 +93,8 @@ allow-direct-references = true
 [tool.hatch.build.targets.wheel]
 packages = ["src/docket"]
 
-[tool.ruff]
-target-version = "py310"
+[tool.hatch.build.targets.sdist]
+exclude = ["conformance-agent"]
 
 [tool.pytest.ini_options]
 addopts = [
@@ -160,9 +151,11 @@ parallel = true
 exclude_also = ["\\.\\.\\.$"]
 
 [tool.pyright]
-include = ["src", "tests", "chaos"]
+include = ["src", "tests", "conformance-agent"]
+# The agent runs as a directory, so its modules import each other from there.
+executionEnvironments = [{ root = "conformance-agent" }]
 typeCheckingMode = "strict"
-venvPath = "."
+venvPath = ".."
 venv = ".venv"
 reportUnnecessaryTypeIgnoreComment = "error"
 reportUnnecessaryCast = "error"

{pydocket-0.26.0 → pydocket-0.26.2}/src/docket/_execution_progress.py

@@ -32,23 +32,7 @@ async def _progress_write(
     payload: Arg[str],
     clear_message: Arg[bool],
     fields: Args[dict[str, str]],
-) -> bytes:
-    """
-    local hset_args = {}
-    for i = fields_start, #ARGV, 2 do
-        hset_args[#hset_args + 1] = ARGV[i]
-        hset_args[#hset_args + 1] = ARGV[i + 1]
-    end
-    if #hset_args > 0 then
-        redis.call('HSET', progress_key, unpack(hset_args))
-    end
-    if clear_message then
-        redis.call('HDEL', progress_key, 'message')
-    end
-    redis.call('PUBLISH', progress_key, payload)
-    return 'OK'
-    """
-    ...
+) -> bytes: ...
 
 
 class ProgressEvent(TypedDict):

pydocket-0.26.2/src/docket/_execution_scripts.py

@@ -0,0 +1,97 @@
+"""The Lua that moves one task key between lifecycle states.
+
+Every transition in a task's life is one atomic script against the keys for
+a single task: ``_schedule`` puts it on the stream or the queue, ``_claim``
+takes it for a worker, ``_terminal`` records how it finished, and
+``_cancel_task`` takes it back off.  The first three each check the
+``generation`` counter in the runs hash, so a stale attempt can never
+overwrite a newer one.
+
+``Execution`` and ``Docket`` call these; the scripts hold no Python logic of
+their own.
+"""
+
+from typing import Any
+
+from ._lua import Arg, Args, Key, redis_script
+from ._redis import RedisClient
+
+
+@redis_script
+async def _schedule(
+    redis: RedisClient,
+    *,
+    stream_key: Key[str],
+    known_key: Key[str],
+    parked_key: Key[str],
+    queue_key: Key[str],
+    stream_id_key: Key[str],
+    runs_key: Key[str],
+    state_channel: Key[str],
+    task_key: Arg[str],
+    when_timestamp: Arg[float],
+    is_immediate: Arg[bool],
+    replace: Arg[bool],
+    reschedule_message_id: Arg[bytes],
+    expected_generation: Arg[int],
+    worker_group_name: Arg[str],
+    state_payload: Arg[str],
+    message: Args[dict[bytes, bytes]],
+) -> bytes | str: ...
+
+
+@redis_script
+async def _claim(
+    redis: RedisClient,
+    *,
+    runs_key: Key[str],
+    progress_key: Key[str],
+    known_key: Key[str],
+    stream_id_key: Key[str],
+    state_channel: Key[str],
+    stream_key: Key[str],
+    worker: Arg[str],
+    started_at: Arg[str],
+    generation: Arg[int],
+    state_payload: Arg[str],
+    key_json: Arg[str],
+    worker_group_name: Arg[str],
+    message_id: Arg[bytes],
+) -> list[Any]: ...
+
+
+@redis_script
+async def _terminal(
+    redis: RedisClient,
+    *,
+    runs_key: Key[str],
+    state_channel: Key[str],
+    progress_key: Key[str],
+    stream_key: Key[str],
+    generation: Arg[int],
+    state: Arg[str],
+    completed_at: Arg[str],
+    ttl_seconds: Arg[int],
+    state_payload: Arg[str],
+    worker_group_name: Arg[str],
+    message_id: Arg[bytes],
+    extra_fields: Args[list[str]],
+) -> bytes: ...
+
+
+@redis_script
+async def _cancel_task(
+    redis: RedisClient,
+    *,
+    stream_key: Key[str],
+    known_key: Key[str],
+    parked_key: Key[str],
+    queue_key: Key[str],
+    stream_id_key: Key[str],
+    runs_key: Key[str],
+    progress_key: Key[str],
+    state_channel: Key[str],
+    task_key: Arg[str],
+    completed_at: Arg[str],
+    state_payload: Arg[str],
+) -> bytes: ...

{pydocket-0.26.0 → pydocket-0.26.2}/src/docket/_lua.py

@@ -2,9 +2,11 @@
 
 The ``@redis_script`` decorator collapses each Lua-backed Redis operation
 into a single callable :class:`RedisScript` whose signature *is* the
-declared function's calling contract and whose docstring *is* the Lua
-source.  Compared with the hand-rolled ``redis.register_script`` +
-lazy-singleton pattern, every script gains:
+declared function's calling contract.  The Lua source lives in
+``protocol/`` at the repository root, shared by every language's docket,
+and a copy ships in this package's ``lua/`` directory.  Compared with the
+hand-rolled ``redis.register_script`` + lazy-singleton pattern, every
+script gains:
 
 * SHA1 computed once at decoration time and reused forever -- no
   per-call ``register_script`` hash work.
@@ -34,25 +36,36 @@ Authoring shape:
         worker: Arg[str],
         started_at: Arg[str],
         generation: Arg[int],
-    ) -> bytes:
-        \"\"\"
-        local runs_key = KEYS[1]
-        -- ... Lua body ...
-        return 'OK'
-        \"\"\"
-        ...
-
-The trailing ``...`` is the standard Python stub idiom -- pyright
-recognises ``docstring + Ellipsis`` as a stub body and stops asking the
-function to ``return`` anything, so no per-function ``# type: ignore``
-is needed.
+    ) -> bytes: ...
+
+The stub's name picks its script: ``_claim`` runs ``lua/claim.lua``.  Each
+script starts with a header that binds ``KEYS`` and ``ARGV`` to local
+names, then a blank line, then the body:
+
+.. code-block:: lua
+
+    local runs_key = KEYS[1]
+    local progress_key = KEYS[2]
+    local worker = ARGV[1]
+    local started_at = ARGV[2]
+    local generation = tonumber(ARGV[3])
+
+    -- ... Lua body ...
+    return 'OK'
+
+The header is the calling contract that every language follows, so the
+decorator checks it against the signature when the module loads, and a
+script whose header and signature disagree fails at import.
 """
 
 from __future__ import annotations
 
 import functools
 import inspect
+import sys
+from importlib.resources import files
 from typing import (
+    TYPE_CHECKING,
     Annotated,
     Any,
     Awaitable,
@@ -73,6 +86,12 @@ from redis.commands.core import AsyncScript
 
 from ._redis import Pipeline, RedisClient
 
+if TYPE_CHECKING:
+    if sys.version_info >= (3, 11):
+        from importlib.resources.abc import Traversable
+    else:
+        from importlib.abc import Traversable
+
 
 # Marker classes used as ``Annotated`` metadata.  The class objects
 # themselves go into ``__metadata__`` -- no instances needed -- and the
@@ -323,23 +342,29 @@ class RedisScript(Generic[_P, _R]):
         pipeline.eval(self.lua, len(keys), *keys, *argv)
 
 
-def redis_script(
-    fn: Callable[Concatenate[RedisClient, _P], Awaitable[_R]],
-) -> RedisScript[_P, _R]:
-    """Wrap an async function declaring a Lua script as its docstring.
+class ScriptDirectory:
+    """A directory of Lua scripts, used as the ``@redis_script`` decorator.
 
-    Returns a :class:`RedisScript`: call it exactly like the declared
-    function to execute immediately, or use ``.enqueue(pipeline, ...)`` to
-    queue it on a pipeline.  See the module docstring for the authoring
-    contract and the encoding rules applied to ``Arg`` / ``Args``
-    parameters.
+    Decorating a stub returns a :class:`RedisScript` that runs the file
+    named after the stub, without its leading underscores: ``_claim`` runs
+    ``claim.lua``.  Call it exactly like the declared function to execute
+    immediately, or use ``.enqueue(pipeline, ...)`` to queue it on a
+    pipeline.  See the module docstring for the authoring contract and the
+    encoding rules applied to ``Arg`` / ``Args`` parameters.
     """
-    body = inspect.getdoc(fn)
-    if not body:
-        raise TypeError(
-            f"@redis_script function {fn.__qualname__} needs a Lua body in its docstring"
-        )
 
+    def __init__(self, directory: Traversable) -> None:
+        self._directory = directory
+
+    def __call__(
+        self, fn: Callable[Concatenate[RedisClient, _P], Awaitable[_R]]
+    ) -> RedisScript[_P, _R]:
+        return _wrap(fn, self._directory)
+
+
+def _wrap(
+    fn: Callable[Concatenate[RedisClient, _P], Awaitable[_R]], directory: Traversable
+) -> RedisScript[_P, _R]:
     sig = inspect.signature(fn)
     hints = get_type_hints(fn, include_extras=True)
 
@@ -390,10 +415,22 @@ def redis_script(
                     f"Args[...] must be the last parameter"
                 )
 
-    preamble = _generate_preamble(key_params, arg_params)
-    lua = f"{preamble}\n\n{body}" if preamble else body
+    # Every language binds KEYS and ARGV the way this header says, so a
+    # header that drifts from the signature would send values to the wrong
+    # slots.  The blank line ends the header, so an extra binding fails too.
+    script_name = fn.__name__.lstrip("_")
+    source = (directory / f"{script_name}.lua").read_text(encoding="utf-8")
+    header = _generate_preamble(key_params, arg_params)
+    if not source.startswith(f"{header}\n\n"):
+        raise TypeError(
+            f"@redis_script: the Lua header for {fn.__qualname__} must be "
+            f"exactly these lines, then a blank line:\n{header}"
+        )
+
+    return RedisScript(fn, source, key_params, arg_params)
+
 
-    return RedisScript(fn, lua, key_params, arg_params)
+redis_script = ScriptDirectory(files("docket") / "lua")
 
 
 __all__ = [
@@ -401,5 +438,6 @@ __all__ = [
     "Args",
     "Key",
     "RedisScript",
+    "ScriptDirectory",
     "redis_script",
 ]

{pydocket-0.26.0 → pydocket-0.26.2}/src/docket/_redelivery.py

@@ -85,14 +85,7 @@ async def _refresh_lease(
     lease_key: Key[str],
     holder: Arg[str],
     duration_ms: Arg[int],
-) -> int:
-    """
-    if redis.call('GET', lease_key) == holder then
-        return redis.call('PEXPIRE', lease_key, duration_ms)
-    end
-    return 0
-    """
-    ...
+) -> int: ...
 
 
 async def renew_leases(