toro-queue 0.6.0__tar.gz → 0.6.1__tar.gz

{toro_queue-0.6.0 → toro_queue-0.6.1}/.github/workflows/pr-check.yaml

@@ -41,13 +41,13 @@ jobs:
           --health-timeout 5s
           --health-retries 5
     steps:
-      - uses: actions/checkout@v6.0.3
+      - uses: actions/checkout@v7.0.1
         with:
           fetch-depth: 0          # full history improves Sonar new-code/blame relevancy
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.2.0
+        uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -72,7 +72,7 @@ jobs:
       # Config is passed inline; there is no sonar-project.properties.
       - name: SonarCloud scan
         if: matrix.python-version == '3.13' && env.SONAR_TOKEN
-        uses: SonarSource/sonarqube-scan-action@v8.2.0
+        uses: SonarSource/sonarqube-scan-action@v8.2.2
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

{toro_queue-0.6.0 → toro_queue-0.6.1}/.github/workflows/release.yml

@@ -12,9 +12,9 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.3
+      - uses: actions/checkout@v7.0.1
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.2.0
+        uses: astral-sh/setup-uv@v10.1.0
       - name: Build sdist + wheel
         run: uv build
       - uses: actions/upload-artifact@v7.0.1

{toro_queue-0.6.0 → toro_queue-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: toro-queue
-Version: 0.6.0
+Version: 0.6.1
 Summary: An async-first, Redis-backed job queue for Python.
 Project-URL: Homepage, https://github.com/ilovepixelart/toro
 Project-URL: Repository, https://github.com/ilovepixelart/toro

{toro_queue-0.6.0 → toro_queue-0.6.1}/docs/processing.md

@@ -56,8 +56,10 @@ event loop - see [workers vs. slots](concepts.md). Two practical consequences:
 - **Connections scale with concurrency.** Each idle slot parks a (blocking-pop)
   connection, so the worker sizes its own pool to `concurrency + headroom`. If
   you pass your own `connection`, size its pool accordingly, and give it a read
-  timeout (`socket_timeout`) above `block_timeout`. redis-py 8 defaults it to 5 s.
-  The worker keeps its blocking pop under whatever it finds, so a tighter read
+  timeout (`socket_timeout`) above `block_timeout`. A `Queue`'s connection
+  already has one for the default `block_timeout`, so sharing it with a worker
+  needs nothing. A client you build yourself gets redis-py's default of 5 s. The
+  worker keeps its blocking pop under whatever it finds, so a tighter read
   timeout means idle slots re-poll sooner than `block_timeout` asks, with a
   warning logged.
 

{toro_queue-0.6.0 → toro_queue-0.6.1}/pyproject.toml

@@ -2,7 +2,7 @@
 # PyPI distribution name - plain `toro` is taken (abandoned). The import package
 # stays `toro` (e.g. `pip install toro-queue` then `import toro`).
 name = "toro-queue"
-version = "0.6.0"
+version = "0.6.1"
 description = "An async-first, Redis-backed job queue for Python."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -57,10 +57,13 @@ package = true
 [tool.ruff]
 line-length = 100
 target-version = "py310"
+# Ruff 0.16 formats Python blocks inside Markdown by default. The docs align
+# trailing comments by hand as teaching annotations, which a formatter flattens.
+extend-exclude = ["*.md"]
 
 [tool.ruff.lint]
 # Strictest sensible baseline: enable everything, then opt out deliberately. The
-# ruff version is pinned (dev deps) so new rules can't surprise CI.
+# lockfile pins ruff, so new rules arrive only with a deliberate `uv lock --upgrade`.
 select = ["ALL"]
 ignore = [
     "COM812", "ISC001",            # conflict with the formatter (per Ruff docs)
@@ -75,6 +78,7 @@ ignore = [
     "PLR0913",                     # Worker/Queue are config constructors - many kwargs is fine
     "BLE001", "S110", "S112",      # deliberate best-effort excepts in worker/redis cleanup paths
     "TC001", "TC002", "TC003",     # prefer normal runtime imports over TYPE_CHECKING blocks
+    "CPY001",                      # the LICENSE file covers the repo; no per-file notices
 ]
 
 [tool.ruff.lint.per-file-ignores]
@@ -113,6 +117,10 @@ python-version = "3.10"
 # Strictest ty: every rule, including the warn-by-default ones, fails the build.
 [tool.ty.rules]
 all = "error"
+# Off by default in ty, and unsound for this codebase. It treats `self._running`
+# as constant across an `await`, where stop() flips it from another task, and it
+# flags the runtime guards on option shapes decoded from JSON stored in Redis.
+redundant-condition-strict = "ignore"
 
 [tool.ty.src]
 include = ["toro"]

{toro_queue-0.6.0 → toro_queue-0.6.1}/tests/unit/test_worker_connection.py

@@ -1,11 +1,13 @@
 """Unit: the connection a Worker builds for itself must outlast its blocking pop."""
 
+import logging
+
 import pytest
 import redis.asyncio as aioredis
 from redis.asyncio.connection import Connection
 
-from toro import Worker
-from toro.connection import read_timeout
+from toro import Queue, Worker
+from toro.connection import DEFAULT_BLOCK_TIMEOUT, read_timeout
 from toro.worker import pop_timeout
 
 
@@ -56,3 +58,27 @@ def test_a_caller_provided_connection_on_library_defaults_is_clamped():
         assert w._pop_timeout == 30.0
     else:
         assert w._pop_timeout < library_default
+
+
+def test_a_queue_built_connection_hosts_a_default_worker_quietly(caplog):
+    """Sharing the Queue's connection with a Worker is an ordinary setup. At the
+    default block_timeout it must neither shorten the pop nor log a warning: a
+    default configuration that warns teaches people to ignore warnings. redis-py's
+    guidance for blocking commands is a socket_timeout above the block window, so
+    every connection toro builds has to be sized for toro's own default pop."""
+    queue = Queue("q")
+    with caplog.at_level(logging.WARNING, logger="toro.worker"):
+        # spelled out: conftest shrinks the default block_timeout in tests
+        w = Worker("q", _noop, connection=queue.redis, block_timeout=DEFAULT_BLOCK_TIMEOUT)
+    assert w._pop_timeout == DEFAULT_BLOCK_TIMEOUT
+    assert [r.getMessage() for r in caplog.records] == []
+
+
+def test_a_pop_longer_than_a_shared_connection_allows_still_warns(caplog):
+    """The warning stays for the case that deserves one: asking for a pop the
+    connection in hand cannot hold."""
+    queue = Queue("q")
+    with caplog.at_level(logging.WARNING, logger="toro.worker"):
+        w = Worker("q", _noop, connection=queue.redis, block_timeout=60.0)
+    assert w._pop_timeout < 60.0
+    assert len(caplog.records) == 1

{toro_queue-0.6.0 → toro_queue-0.6.1}/toro/__init__.py

@@ -26,4 +26,4 @@ __all__ = [
     "ToroError",
     "Worker",
 ]
-__version__ = "0.6.0"
+__version__ = "0.6.1"

toro_queue-0.6.1/toro/_replies.py

@@ -0,0 +1,31 @@
+"""The one place a raw Redis reply gets its Python type.
+
+Every client runs with ``decode_responses`` on, so replies are ``str`` at runtime,
+while redis-py types them as ``bytes | str``. These helpers name that boundary once.
+They take ``Any`` on purpose: ``dict`` and ``list`` are invariant, so a cast straight
+from redis-py's declared type is a cast between unrelated types, not a narrowing.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+
+def _str_list(reply: Any) -> list[str]:
+    """Type a Redis list/zset reply as list[str]."""
+    return cast("list[str]", reply)
+
+
+def _str_dict(reply: Any) -> dict[str, str]:
+    """Type a Redis hash reply as dict[str, str]."""
+    return cast("dict[str, str]", reply)
+
+
+def _hash_replies(reply: Any) -> list[dict[str, str]]:
+    """Type a pipeline's list of hash replies as list[dict[str, str]]."""
+    return cast("list[dict[str, str]]", reply)
+
+
+def _scored(reply: Any) -> list[tuple[str, float]]:
+    """Type a zset reply read WITHSCORES as list[(member, score)]."""
+    return cast("list[tuple[str, float]]", reply)

{toro_queue-0.6.0 → toro_queue-0.6.1}/toro/connection.py

@@ -2,20 +2,23 @@
 
 from __future__ import annotations
 
-from typing import Any
-
 import redis.asyncio as aioredis
 from redis.asyncio.retry import Retry
 from redis.backoff import ExponentialBackoff
 from redis.exceptions import ConnectionError as RedisConnectionError
 from redis.exceptions import TimeoutError as RedisTimeoutError
 
+# How long an idle worker slot blocks on the marker by default. It lives here, not
+# in worker.py, because every connection toro builds is sized for it: a Queue's
+# connection is routinely shared with a Worker, and must hold that worker's pop.
+DEFAULT_BLOCK_TIMEOUT = 5.0
+
 # How far a connection's read timeout sits above the longest blocking pop it serves.
 READ_MARGIN = 5.0
 
 
 def connect(
-    url: str, *, max_connections: int = 50, blocking_timeout: float | None = None
+    url: str, *, max_connections: int = 50, blocking_timeout: float = DEFAULT_BLOCK_TIMEOUT
 ) -> aioredis.Redis:
     """Open a ``decode_responses`` client tuned for toro's long-lived connections.
 
@@ -38,20 +41,20 @@ def connect(
     ``blocking_timeout`` is the longest server-side block this client will issue.
     The read timeout is set above it: a blocking pop has to come back before the
     client gives up on the read, or it raises instead of timing out quietly.
-    redis-py 8 defaults the read timeout to 5s, which a 5s pop does not beat.
+    redis-py's own guidance for blocking commands is a ``socket_timeout`` larger
+    than the block window, and its default of 5s does not beat a 5s pop. The
+    default here fits a default worker, so a Queue's connection can be handed to
+    one as it is.
     """
-    extra: dict[str, Any] = {}
-    if blocking_timeout is not None:
-        extra["socket_timeout"] = blocking_timeout + READ_MARGIN
     pool = aioredis.BlockingConnectionPool.from_url(
         url,
         max_connections=max_connections,
         decode_responses=True,
         health_check_interval=30,
         socket_keepalive=True,
+        socket_timeout=blocking_timeout + READ_MARGIN,
         retry=Retry(ExponentialBackoff(), retries=3),
         retry_on_error=[RedisConnectionError, RedisTimeoutError],
-        **extra,
     )
     return aioredis.Redis(connection_pool=pool)
 
@@ -64,4 +67,5 @@ def read_timeout(client: aioredis.Redis) -> float | None:
     The factory is what a pool subclass overrides, and building the object opens
     nothing.
     """
-    return client.connection_pool.make_connection().socket_timeout
+    timeout = client.connection_pool.make_connection().socket_timeout
+    return None if timeout is None else float(timeout)

{toro_queue-0.6.0 → toro_queue-0.6.1}/toro/job.py

@@ -8,6 +8,8 @@ from typing import Any, Literal, Protocol, TypeAlias, TypedDict, cast
 
 from redis.asyncio import Redis
 
+from ._replies import _str_dict
+
 # The lifecycle states a job can be in (also the queryable states for get_jobs).
 # `waiting-children` is the flow-parent park: enqueued, but runnable only once
 # every child has settled.
@@ -177,9 +179,7 @@ class Job:
         """
         if self._ctx is None:
             raise RuntimeError("children_results() is only available inside a worker processor")
-        return decode_results(
-            cast("dict[str, str]", await self._ctx.redis.hgetall(self._ctx.results_key))
-        )
+        return decode_results(_str_dict(await self._ctx.redis.hgetall(self._ctx.results_key)))
 
     async def failed_children(self) -> dict[str, str]:
         """Pull child id -> failure reason for children failed under
@@ -187,7 +187,7 @@ class Job:
         """
         if self._ctx is None:
             raise RuntimeError("failed_children() is only available inside a worker processor")
-        return cast("dict[str, str]", await self._ctx.redis.hgetall(self._ctx.cfail_key))
+        return _str_dict(await self._ctx.redis.hgetall(self._ctx.cfail_key))
 
     @classmethod
     def from_hash(cls, job_id: str, h: dict[str, str]) -> Job:

{toro_queue-0.6.0 → toro_queue-0.6.1}/toro/queue.py

@@ -13,6 +13,7 @@ from redis.asyncio import Redis
 from redis.asyncio.client import PubSub
 
 from . import scripts
+from ._replies import _hash_replies, _scored, _str_dict, _str_list
 from .connection import connect
 from .errors import JobFailedError
 from .flow import MAX_FLOW_NODES, FlowChild, FlowView, count_nodes, node_options, to_tree
@@ -26,21 +27,6 @@ def _now_ms() -> int:
     return int(time.time() * 1000)
 
 
-def _str_list(reply: Any) -> list[str]:
-    """Type a Redis list/zset reply (decode_responses is on) as list[str]."""
-    return cast("list[str]", reply)
-
-
-def _str_dict(reply: Any) -> dict[str, str]:
-    """Type a Redis hash reply (decode_responses is on) as dict[str, str]."""
-    return cast("dict[str, str]", reply)
-
-
-def _hash_replies(reply: Any) -> list[dict[str, str]]:
-    """Type a pipeline's list of hash replies as list[dict[str, str]]."""
-    return cast("list[dict[str, str]]", reply)
-
-
 class MetricsPoint(TypedDict):
     """One minute of queue activity: counts + summed processing duration."""
 
@@ -556,10 +542,7 @@ class Queue:
 
     async def schedulers(self) -> list[dict[str, Any]]:
         """List active schedulers (for the dashboard)."""
-        entries = cast(
-            "list[tuple[str, float]]",
-            await self.redis.zrange(self.keys.repeat, 0, -1, withscores=True),
-        )
+        entries = _scored(await self.redis.zrange(self.keys.repeat, 0, -1, withscores=True))
         if not entries:
             return []
         pipe = self.redis.pipeline(transaction=False)  # read fan-out; no MULTI/EXEC needed
@@ -860,8 +843,11 @@ class Queue:
             return self.keys.delayed, False
         if state == "waiting-children":
             return self.keys.waiting_children, False
-        if state in ("completed", "failed"):
-            return getattr(self.keys, state), True  # finished states read newest-first
+        # finished states read newest-first
+        if state == "completed":
+            return self.keys.completed, True
+        if state == "failed":
+            return self.keys.failed, True
         raise ValueError(f"unknown state: {state}")
 
     async def get_jobs_roots(

{toro_queue-0.6.0 → toro_queue-0.6.1}/toro/worker.py

@@ -33,7 +33,8 @@ from typing import Any, TypedDict, cast
 from redis.asyncio import Redis
 
 from . import scripts
-from .connection import connect, read_timeout
+from ._replies import _str_list
+from .connection import DEFAULT_BLOCK_TIMEOUT, connect, read_timeout
 from .job import Backoff, Job, JobContext, JobOptions
 from .keys import Keys
 from .scheduler import next_run
@@ -106,7 +107,7 @@ class Worker:
         concurrency: int = 1,
         rate_limit: RateLimit | None = None,
         global_concurrency: int | None = None,
-        block_timeout: float = 5.0,
+        block_timeout: float = DEFAULT_BLOCK_TIMEOUT,
         lock_duration: int = 30000,
         lock_renew_time: int | None = None,
         renew_locks: bool = True,
@@ -385,7 +386,7 @@ class Worker:
         fields = _pairs(res[0])
         if not fields:
             return None
-        return (res[1], fields)
+        return (str(res[1]), fields)
 
     async def _handle(
         self, loaded: tuple[str, dict[str, str]]
@@ -542,7 +543,7 @@ class Worker:
 
     def _next_from(self, res: Any) -> tuple[str, dict[str, str]] | None:
         if isinstance(res, (list, tuple)) and len(res) >= 3:
-            return (res[2], _pairs(res[1]))
+            return (str(res[2]), _pairs(res[1]))
         return None
 
     # ---- locks & recovery -------------------------------------------------
@@ -623,8 +624,8 @@ class Worker:
             ],
             args=[self.max_stalled_count, _now_ms(), throttle, scripts.METRICS_RETENTION_MS],
         )
-        failed = list(res[0]) if res else []
-        recovered = list(res[1]) if res and len(res) > 1 else []
+        failed = _str_list(res[0]) if res else []
+        recovered = _str_list(res[1]) if res and len(res) > 1 else []
         return failed, recovered
 
     def _backoff_delay(self, job: Job) -> int: