toro-queue 0.2.0__tar.gz → 0.3.0__tar.gz

{toro_queue-0.2.0 → toro_queue-0.3.0}/.github/workflows/pr-check.yaml

@@ -9,7 +9,7 @@ on:
   pull_request:
     types: [opened, synchronize, reopened]
 
-# Read-only by default — nothing here writes to the repo. SonarCloud PR
+# Read-only by default - nothing here writes to the repo. SonarCloud PR
 # decoration comes from the SonarCloud GitHub App, not GITHUB_TOKEN write scopes.
 permissions:
   contents: read
@@ -68,7 +68,7 @@ jobs:
         run: uv run pytest -m "unit or integration" --cov=toro --cov-report=xml
 
       # Runs only when SONAR_TOKEN is set (skipped on forks / before setup, so the
-      # check stays green), and only once per matrix — one coverage upload.
+      # check stays green), and only once per matrix - one coverage upload.
       # Config is passed inline; there is no sonar-project.properties.
       - name: SonarCloud scan
         if: matrix.python-version == '3.13' && env.SONAR_TOKEN

{toro_queue-0.2.0 → toro_queue-0.3.0}/.github/workflows/release.yml

@@ -1,7 +1,7 @@
 name: Release
 
 # A version tag (v*) builds and publishes to PyPI via trusted publishing (OIDC)
-# — no API tokens stored. The publish job runs in the `pypi` environment, which
+# - no API tokens stored. The publish job runs in the `pypi` environment, which
 # must match the trusted publisher registered on PyPI.
 on:
   push:

toro_queue-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+# All hooks run through `uv run`, so versions come from the lockfile - one
+# source of truth shared by pre-commit, CI and dev, nothing to drift.
+# Install once with:  uvx pre-commit install
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --force-exclude
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format --check --force-exclude
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+
+      - id: ty
+        name: ty type check
+        entry: uv run ty check
+        language: system
+        pass_filenames: false
+        types: [python]

{toro_queue-0.2.0 → toro_queue-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: toro-queue
-Version: 0.2.0
+Version: 0.3.0
 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
@@ -55,12 +55,12 @@ Pairs with **[matador](https://github.com/ilovepixelart/matador)**, a live web d
 
 ## Why toro
 
-- **Async-native.** Enqueue and process with `async`/`await` — no thread pools,
+- **Async-native.** Enqueue and process with `async`/`await` - no thread pools,
   no sync bridge. A natural fit for FastAPI, aiohttp, or any asyncio app.
 - **Atomic by construction.** Claims, retries, promotions and finishes are Lua
   scripts, so a job can't be lost or double-committed between two round trips.
 - **At-least-once delivery.** Per-job locks + a background mark-and-sweep recover
-  jobs from workers that crashed — without the visibility-timeout double-delivery
+  jobs from workers that crashed - without the visibility-timeout double-delivery
   trap of some other queues.
 - **Typed.** Ships `py.typed`; the public API is fully annotated.
 
@@ -77,7 +77,7 @@ Pairs with **[matador](https://github.com/ilovepixelart/matador)**, a live web d
 | **Reliability** | per-job locks, lock renewal, stalled-job recovery |
 | **Observability** | progress, per-job logs, lifecycle events, `await result()` |
 | **Lifecycle** | pause / resume, graceful shutdown that drains in-flight jobs |
-| **Dashboard** | [matador](https://github.com/ilovepixelart/matador) — a live web UI |
+| **Dashboard** | [matador](https://github.com/ilovepixelart/matador) - a live web UI |
 
 ## Quick start
 
@@ -134,7 +134,7 @@ uv run pytest -m "unit or integration"   # tests (integration needs Redis on :63
 uv run python examples/basic.py
 ```
 
-The suite is a pyramid — `-m unit` (fast, no Redis), `-m integration` (Redis),
+The suite is a pyramid - `-m unit` (fast, no Redis), `-m integration` (Redis),
 and `-m load` (the open-loop benchmark harness in `tests/load/`).
 
 ## License

{toro_queue-0.2.0 → toro_queue-0.3.0}/README.md

@@ -28,12 +28,12 @@ Pairs with **[matador](https://github.com/ilovepixelart/matador)**, a live web d
 
 ## Why toro
 
-- **Async-native.** Enqueue and process with `async`/`await` — no thread pools,
+- **Async-native.** Enqueue and process with `async`/`await` - no thread pools,
   no sync bridge. A natural fit for FastAPI, aiohttp, or any asyncio app.
 - **Atomic by construction.** Claims, retries, promotions and finishes are Lua
   scripts, so a job can't be lost or double-committed between two round trips.
 - **At-least-once delivery.** Per-job locks + a background mark-and-sweep recover
-  jobs from workers that crashed — without the visibility-timeout double-delivery
+  jobs from workers that crashed - without the visibility-timeout double-delivery
   trap of some other queues.
 - **Typed.** Ships `py.typed`; the public API is fully annotated.
 
@@ -50,7 +50,7 @@ Pairs with **[matador](https://github.com/ilovepixelart/matador)**, a live web d
 | **Reliability** | per-job locks, lock renewal, stalled-job recovery |
 | **Observability** | progress, per-job logs, lifecycle events, `await result()` |
 | **Lifecycle** | pause / resume, graceful shutdown that drains in-flight jobs |
-| **Dashboard** | [matador](https://github.com/ilovepixelart/matador) — a live web UI |
+| **Dashboard** | [matador](https://github.com/ilovepixelart/matador) - a live web UI |
 
 ## Quick start
 
@@ -107,7 +107,7 @@ uv run pytest -m "unit or integration"   # tests (integration needs Redis on :63
 uv run python examples/basic.py
 ```
 
-The suite is a pyramid — `-m unit` (fast, no Redis), `-m integration` (Redis),
+The suite is a pyramid - `-m unit` (fast, no Redis), `-m integration` (Redis),
 and `-m load` (the open-loop benchmark harness in `tests/load/`).
 
 ## License

{toro_queue-0.2.0 → toro_queue-0.3.0}/docs/architecture.md

@@ -12,9 +12,9 @@ Every state move (`wait→active`, `active→completed/failed/delayed`,
 `delayed→wait`) is a single Redis Lua script, run atomically, so multi-key
 "check-then-act" sequences can't interleave. That removes whole classes of race:
 
-- **pop-then-lock gap** — two workers claiming the same job: the claim pops from
+- **pop-then-lock gap** - two workers claiming the same job: the claim pops from
   the priority set and sets the lock inside one script.
-- **finish-after-steal** — a worker committing a result for a job a stalled sweep
+- **finish-after-steal** - a worker committing a result for a job a stalled sweep
   already re-queued: guarded by a token check plus `LREM active` returning 0.
 
 Scripts live in `scripts.py`, registered with `redis.asyncio`'s `register_script`.
@@ -23,7 +23,7 @@ The Python side only assembles KEYS/ARGV; the guarantees live in the Lua.
 ## Claiming a job: the prioritized set + a wakeup marker
 
 All waiting jobs live in one `prioritized` ZSET, scored
-`(PRIORITY_OFFSET - priority) * 2^32 + seq` — a single global order where higher
+`(PRIORITY_OFFSET - priority) * 2^32 + seq` - a single global order where higher
 priority is more urgent and ties stay FIFO (`seq` is a per-queue counter). This
 *is* the `wait` state; there is no separate fast-lane list, so a low-priority job
 can't starve a high-priority one.
@@ -74,19 +74,19 @@ due jobs into the prioritized set.
 
 ## Higher-level features
 
-- **Priorities** — every job is in the one prioritized ZSET above, so priority is
+- **Priorities** - every job is in the one prioritized ZSET above, so priority is
   a single global order with no starvation, FIFO within a band.
-- **Repeatable / cron** — `add_scheduler(every=ms | cron=...)` stores a template
+- **Repeatable / cron** - `add_scheduler(every=ms | cron=...)` stores a template
   and enqueues the first occurrence as a delayed job; each occurrence mints its
   successor with a deterministic id when a worker picks it up. `trigger_scheduler`
   runs one now, `remove_scheduler` stops the chain. See [Scheduling](scheduling.md).
-- **Rate limiting** — a queue-wide token bucket in Redis
+- **Rate limiting** - a queue-wide token bucket in Redis
   (`Worker(rate_limit={"max": N, "duration": ms})`), shared by every worker on the
   queue. An over-limit claim returns a sentinel and the worker waits out the window.
-- **Events** — Redis pub/sub on an `events` channel (`added`, `progress`,
+- **Events** - Redis pub/sub on an `events` channel (`added`, `progress`,
   `completed`, `failed`); `Queue.result()` awaits the terminal event and
   `Worker.on(event, fn)` exposes in-process hooks. See [Concepts](concepts.md).
-- **Auto-removal** — `remove_on_complete` / `remove_on_fail` (bool / count /
+- **Auto-removal** - `remove_on_complete` / `remove_on_fail` (bool / count /
   `{count, age}`) enforced inside the finish script, not by a separate sweeper.
 
 ## The Lua scripts
@@ -123,21 +123,21 @@ And the scripts themselves:
 
 Scripts signal outcomes with sentinels the worker decodes:
 
-- `RL_SENTINEL` (`"__rl__"`) — a claim hit the rate limiter; the second value is
+- `RL_SENTINEL` (`"__rl__"`) - a claim hit the rate limiter; the second value is
   ms until a token frees, so the worker waits instead of busy-spinning.
-- `LOCK_LOST` (`-2`) — a finish ran but the worker no longer held the lock (the
+- `LOCK_LOST` (`-2`) - a finish ran but the worker no longer held the lock (the
   job was reclaimed); the result is dropped.
-- `NOT_ACTIVE` (`-3`) — a finish ran but the job was no longer in `active`.
-- `OUTCOME_FAILED` (`1`) vs `0` — `MOVE_TO_FAILED` telling the worker whether the
+- `NOT_ACTIVE` (`-3`) - a finish ran but the job was no longer in `active`.
+- `OUTCOME_FAILED` (`1`) vs `0` - `MOVE_TO_FAILED` telling the worker whether the
   job terminally failed or will retry.
 
 Scores are packed under 2^53 (`PRIORITY_OFFSET = 2^20`, `SEQ_MOD = 2^32`) so ZSET
-double scores stay exact, and the scripts use only plain JSON and integer ARGV —
-no `cmsgpack` / `bit` / `cjson` — so they run on any Redis build.
+double scores stay exact, and the scripts use only plain JSON and integer ARGV -
+no `cmsgpack` / `bit` / `cjson` - so they run on any Redis build.
 
 ## Python-specific choices
 
-- **async-first** — `redis.asyncio`, `async def` processors, one event loop;
+- **async-first** - `redis.asyncio`, `async def` processors, one event loop;
   concurrency is N `asyncio` tasks sharing the loop.
-- **Cluster** — a `{braces}` hash-tag in the prefix keeps all of a queue's keys on
+- **Cluster** - a `{braces}` hash-tag in the prefix keeps all of a queue's keys on
   one slot, which the multi-key Lua scripts require.

{toro_queue-0.2.0 → toro_queue-0.3.0}/docs/concepts.md

@@ -20,7 +20,7 @@ toro has a clean producer/consumer split, and both talk to the same Redis.
   bookkeeping the system fills in: `state`, `attempts_made`, timestamps
   (`timestamp`, `processed_on`, `finished_on`), `progress`, `stacktrace`, and
   either a `returnvalue` or a `failed_reason`. (A job's log lines and its lock
-  live in separate Redis keys, not as fields on the `Job` — see the
+  live in separate Redis keys, not as fields on the `Job` - see the
   [data model](data-model.md).)
 
 Producers and consumers never call each other. They coordinate only through
@@ -91,7 +91,7 @@ not on a retry. Two things consume the channel:
 
 `Worker.on(event, fn)` lets a worker react to its own lifecycle with in-process
 callbacks (`completed`, `failed`, `retrying`, `stalled`, `lock-lost`,
-`rate-limited`) — separate from the pub/sub channel above. See
+`rate-limited`) - separate from the pub/sub channel above. See
 [Processing jobs](processing.md).
 
 ## Reliability in one sentence

toro_queue-0.3.0/docs/index.md

@@ -0,0 +1,22 @@
+# toro documentation
+
+Reference docs for how toro works. The [README](../README.md) is the quick start.
+
+## Pages
+
+- **[Concepts](concepts.md)** - the mental model: queues, workers, jobs, the five
+  job states, and the difference between *workers* and *slots*.
+- **[Data model](data-model.md)** - the exact Redis keys a queue uses and what
+  each one stores.
+- **[Reliability](reliability.md)** - the at-least-once guarantee: per-job locks,
+  worker tokens, and stalled-job recovery.
+- **[Producing jobs](producing.md)** - `Queue.add()` and every option (priority,
+  delay, retries/backoff, deduplication, custom ids).
+- **[Processing jobs](processing.md)** - `Worker`: concurrency, lifecycle events,
+  rate limiting, and graceful shutdown.
+- **[Scheduling](scheduling.md)** - repeatable and cron jobs, and how each
+  occurrence schedules the next.
+- **[Architecture](architecture.md)** - the atomic-Lua core and the design
+  decisions behind the queue.
+- **[Security](security.md)** - what toro guarantees (JSON-only, no dynamic
+  dispatch, no string-built commands) and what you own (Redis access, secrets).

{toro_queue-0.2.0 → toro_queue-0.3.0}/docs/processing.md

@@ -16,7 +16,7 @@ await worker.run()                   # awaits until stop()
 
 The processor is an `async` function of one argument, the `Job`. Returning
 commits the job as `completed` (the return value, JSON-serialized, becomes
-`returnvalue`); raising routes it through the retry policy — back to the queue
+`returnvalue`); raising routes it through the retry policy - back to the queue
 (or to `delayed` under [backoff](producing.md)) while attempts remain, then
 terminally `failed` with the exception text and a `stacktrace` field.
 
@@ -37,7 +37,7 @@ async def handle(job):
 ## Concurrency
 
 `concurrency=N` runs N processing loops ("slots") as `asyncio` tasks on one
-event loop — see [workers vs. slots](concepts.md). Two practical consequences:
+event loop - see [workers vs. slots](concepts.md). Two practical consequences:
 
 - **Stay `await`-y.** Slots are not threads: CPU-bound or blocking code stalls
   every sibling slot *and* the lock renewers that keep your jobs from being
@@ -47,7 +47,7 @@ event loop — see [workers vs. slots](concepts.md). Two practical consequences:
   you pass your own `connection`, size its pool accordingly.
 
 A busy slot doesn't return to the blocking wait between jobs: the finish call
-also claims the next job in the same round trip (fetch-next — see
+also claims the next job in the same round trip (fetch-next - see
 [Architecture](architecture.md)), so a saturated worker runs at one round trip
 per job.
 
@@ -56,10 +56,10 @@ per job.
 | Option | Default | Meaning |
 |---|---|---|
 | `concurrency` | 1 | Parallel slots in this worker. |
-| `rate_limit` | `None` | `{"max": N, "duration": ms}` — queue-wide token bucket (below). |
+| `rate_limit` | `None` | `{"max": N, "duration": ms}` - queue-wide token bucket (below). |
 | `block_timeout` | 5.0 s | How long an idle slot blocks waiting for a wakeup before re-checking. |
-| `lock_duration` / `lock_renew_time` / `renew_locks` | 30000 / half / `True` | The at-least-once lease — see [Reliability](reliability.md). |
-| `stalled_interval` / `max_stalled_count` | 30000 / 1 | The recovery sweep — same page. |
+| `lock_duration` / `lock_renew_time` / `renew_locks` | 30000 / half / `True` | The at-least-once lease - see [Reliability](reliability.md). |
+| `stalled_interval` / `max_stalled_count` | 30000 / 1 | The recovery sweep - same page. |
 | `grace_period` | 30.0 s | Default drain window for `stop()`. |
 | `heartbeat_interval` | 5000 ms | Presence cadence for the workers view. |
 
@@ -69,7 +69,7 @@ per job.
 worker = Worker("emails", handle, rate_limit={"max": 100, "duration": 60_000})
 ```
 
-At most `max` jobs start per `duration`, across **all** workers on the queue —
+At most `max` jobs start per `duration`, across **all** workers on the queue -
 the token bucket lives in Redis, shared, so adding workers doesn't multiply the
 limit (give every worker the same config). When a claim hits the limit the job
 goes back untouched: no attempt is consumed, and the worker sleeps until a token
@@ -82,14 +82,14 @@ frees (emitting a `rate-limited` event with the wait).
 | Event | Args | When |
 |---|---|---|
 | `completed` | `job, result` | A job committed successfully. |
-| `failed` | `job, exc` | A job failed terminally. The sweep fires it too for stall-failed jobs — there with the job *id* (not a `Job`) and a `RuntimeError("job stalled too many times")`, while the job hash's `failedReason` reads `"job stalled more than allowable limit"`. |
+| `failed` | `job, exc` | A job failed terminally. The sweep fires it too for stall-failed jobs - there with the job *id* (not a `Job`) and a `RuntimeError("job stalled too many times")`, while the job hash's `failedReason` reads `"job stalled more than allowable limit"`. |
 | `retrying` | `job, exc` | A failure with attempts left was re-queued. |
 | `stalled` | `job_id` | The sweep recovered one of this queue's jobs. |
 | `lock-lost` | `job_id` | This worker's lock was taken over; its result was dropped. |
 | `rate-limited` | `retry_ms` | A claim hit the rate limit. |
 
 These are this worker's own hooks. Cross-process consumers (dashboards,
-`result()`) use the pub/sub events channel instead — see [Concepts](concepts.md).
+`result()`) use the pub/sub events channel instead - see [Concepts](concepts.md).
 
 ## Presence
 
@@ -97,7 +97,7 @@ Every `heartbeat_interval` the worker flushes a presence record (host, pid,
 concurrency, what it's running, processed/failed counts, state). That powers the
 dashboard's workers view; a worker that misses heartbeats long enough is pruned
 and logged as a `lost` departure, while `stop()` flips it to a visible
-`stopping` state first and logs `stopped` — so the dashboard can tell a drain
+`stopping` state first and logs `stopped` - so the dashboard can tell a drain
 from a crash.
 
 ## Shutdown
@@ -108,5 +108,5 @@ await worker.stop()        # or stop(grace_period=10)
 
 `stop()` stops claiming new jobs, lets in-flight jobs finish for up to the grace
 period, cancels whatever remains (those jobs' locks expire and the sweep
-recovers them — nothing is lost), deregisters presence, and closes the
+recovers them - nothing is lost), deregisters presence, and closes the
 connection. Pair `run()`/`stop()` with your framework's startup/shutdown hooks.

{toro_queue-0.2.0 → toro_queue-0.3.0}/docs/producing.md

@@ -11,7 +11,7 @@ job = await queue.add("welcome", {"user_id": 42})
 ```
 
 `add(name, data=None, *, job_id=None, deduplication=None, **options)` writes the
-job hash and enqueues (or delays) it in one atomic script — the `added` event is
+job hash and enqueues (or delays) it in one atomic script - the `added` event is
 published from inside that script, so an enqueue is a single round trip and the
 event can't be lost between the two.
 
@@ -35,19 +35,19 @@ Per-queue defaults go on the constructor and merge under per-call options:
 queue = Queue("emails", default_job_options={"remove_on_complete": 1000, "attempts": 3})
 ```
 
-Auto-removal is enforced inside the finish script itself — there is no separate
+Auto-removal is enforced inside the finish script itself - there is no separate
 cleanup process to run or forget.
 
 ## Custom ids and deduplication
 
 Two distinct tools, usable independently:
 
-- **`job_id="order-123"`** — id-based dedup. Adding a job whose id already
+- **`job_id="order-123"`** - id-based dedup. Adding a job whose id already
   exists is idempotent: nothing is enqueued and the existing job's id comes
   back. The id frees up when the job is removed (including by auto-removal).
-  Must be a non-empty, non-all-digits string — all-digit ids would collide with
+  Must be a non-empty, non-all-digits string - all-digit ids would collide with
   auto-generated ones.
-- **`deduplication={"id": "sync-user-42", "ttl": 60_000}`** — a throttle window.
+- **`deduplication={"id": "sync-user-42", "ttl": 60_000}`** - a throttle window.
   While the ttl lives, repeat adds with the same dedup id are ignored and the
   already-queued job's id is returned. Self-expiring; nothing to clean up at
   finish time.
@@ -65,7 +65,7 @@ value = await job.result(timeout=30)        # or queue.result(job.id)
 `result()` resolves with the processor's return value, raises `JobFailedError`
 on terminal failure, or `TimeoutError` after `timeout`. It registers for the
 job's events *before* checking state, so a job that finishes while you wait is
-never missed — and it works even when the job hash was auto-removed, as long as
+never missed - and it works even when the job hash was auto-removed, as long as
 `result()` was awaited before the job finished. A retrying job keeps you
 waiting; only the terminal outcome resolves the call.
 
@@ -77,9 +77,12 @@ waiting; only the terminal outcome resolves the call.
 | `await queue.get_job(job_id)` | A `Job` snapshot, or `None`. |
 | `await queue.get_jobs(state, start, end)` | A page of jobs; `wait` comes back in global priority order, finished states newest-first. |
 | `await queue.get_logs(job_id)` | Log lines appended by the processor. |
-| `await queue.search(state, query, scan_limit=500)` | Substring match over `name`/`data` within the most recent `scan_limit` jobs of a state. A bounded scan, not an index — surface the bound honestly in UIs. |
+| `await queue.search(state, query, scan_limit=500)` | Substring match over `name`/`data` within the most recent `scan_limit` jobs of a state. A bounded scan, not an index - surface the bound honestly in UIs. |
 | `await queue.workers()` | Live workers from their heartbeats; stale entries are pruned (and logged as `lost`) on read. |
 | `await queue.departed_workers()` | Recent departures, newest first: graceful `stopped` or crashed `lost`. |
+| `await queue.metrics(minutes=60)` | Per-minute `{timestamp, added, completed, failed, ms}` points, oldest first, zero-filled for charting. Counters are written inside the same atomic scripts as the transitions (a count can never disagree with the state change it counts); `added` counts real inserts (dedup hits and id replays don't count), `failed` means terminal failures - retries don't count, stall-failures do. Buckets expire after 8 hours. |
+| `await queue.metrics_by_name(minutes=60)` | Per-job-name `{name, completed, failed, ms}` totals over the window, failures first - the triage order ("which job is responsible"), not the volume order. |
+| `await queue.latency()` | Age (ms) of the next-to-run waiting job, `0` when nothing waits. Depth says how much is queued; latency says how far behind the workers are. |
 
 ## Admin operations
 
@@ -93,7 +96,7 @@ waiting; only the terminal outcome resolves the call.
 | `await queue.pause()` / `resume()` / `is_paused()` | Stop workers claiming new jobs (in-flight jobs finish); resume wakes idle workers. |
 
 These are the operations a dashboard such as
-[matador](https://github.com/ilovepixelart/matador) calls under its buttons —
+[matador](https://github.com/ilovepixelart/matador) calls under its buttons -
 they're ordinary public API.
 
 ## Lifecycle

{toro_queue-0.2.0 → toro_queue-0.3.0}/docs/reliability.md

@@ -19,7 +19,7 @@ is exactly what turns a dead worker's jobs back into runnable ones.
 
 While the job runs, a per-job **renewer** task extends the lock every
 `lock_renew_time` (default `lock_duration / 2`) and clears the job from the
-`stalled` candidate set. Renewal is token-guarded — a worker can never renew a
+`stalled` candidate set. Renewal is token-guarded - a worker can never renew a
 lock another worker has since taken over. If a renewal finds the token gone, the
 worker emits `lock-lost` and stops touching the job.
 
@@ -39,7 +39,7 @@ per interval, not once per worker:
    becoming a candidate for the *next* sweep.
 
 A healthy job is marked, then unmarked by its renewer before the next sweep ever
-sees it. Only a job whose worker stopped renewing — i.e. died — stays marked
+sees it. Only a job whose worker stopped renewing - i.e. died - stays marked
 with an expired lock long enough to be recovered. The whole pass is one Lua
 script, so recovery can't race a finish.
 
@@ -48,9 +48,9 @@ script, so recovery can't race a finish.
 The handler may run more than once; the *result* is committed exactly once. The
 finish scripts (`MOVE_TO_COMPLETED` / `MOVE_TO_FAILED`) begin with two guards:
 
-- the lock must still hold **this worker's token** — otherwise the script
+- the lock must still hold **this worker's token** - otherwise the script
   returns `LOCK_LOST` (-2) and commits nothing;
-- the job must still be in `active` — otherwise `NOT_ACTIVE` (-3), same result.
+- the job must still be in `active` - otherwise `NOT_ACTIVE` (-3), same result.
 
 So when a slow worker comes back from the dead after its job was recovered and
 re-run elsewhere, its late finish is dropped on the floor, with a `lock-lost`
@@ -75,10 +75,10 @@ are bounded by `max_stalled_count`.
 
 Two different counters bound two different failure modes:
 
-- `attempts_made` vs `attempts` — *your code failed*: the processor raised.
+- `attempts_made` vs `attempts` - *your code failed*: the processor raised.
   Decided at finish time; retries re-enqueue (with [backoff](producing.md) if
   configured) until attempts run out, then the job fails with your exception.
-- `stalledCounter` vs `max_stalled_count` — *the worker failed*: nobody renewed
+- `stalledCounter` vs `max_stalled_count` - *the worker failed*: nobody renewed
   the lock. Decided by the sweep; bounds how many times an apparently
   worker-killing job is allowed to take a worker down with it.
 
@@ -86,7 +86,7 @@ Two different counters bound two different failure modes:
 
 | Worker option | Default | Meaning |
 |---|---|---|
-| `lock_duration` | 30000 ms | Lock lease length. Must comfortably exceed your event-loop stalls, not your job length — the renewer handles long jobs. |
+| `lock_duration` | 30000 ms | Lock lease length. Must comfortably exceed your event-loop stalls, not your job length - the renewer handles long jobs. |
 | `lock_renew_time` | `lock_duration / 2` | Renewal cadence. |
 | `renew_locks` | `True` | Disable only to *test* stalled recovery. |
 | `stalled_interval` | 30000 ms | Sweep cadence; `0` disables the sweep entirely. |

{toro_queue-0.2.0 → toro_queue-0.3.0}/docs/scheduling.md

@@ -23,12 +23,12 @@ every occurrence.
 
 ## The two cadences
 
-- **`every=ms`** — slot-aligned to the interval grid: the next run is the next
+- **`every=ms`** - slot-aligned to the interval grid: the next run is the next
   multiple of `every` on the wall clock, not "last run + interval". Successive
   runs don't drift, and a late tick (worker down for a while) catches up to the
   *next* slot instead of firing a backlog burst.
-- **`cron="*/5 * * * *"`** — a standard cron expression, evaluated in **UTC**
-  via [croniter](https://pypi.org/project/croniter/) — an optional dependency
+- **`cron="*/5 * * * *"`** - a standard cron expression, evaluated in **UTC**
+  via [croniter](https://pypi.org/project/croniter/) - an optional dependency
   (`pip install croniter`). Expressions are validated at `add_scheduler` time,
   so a typo fails at registration, not silently inside a worker later.
 
@@ -41,13 +41,13 @@ id:
 repeat:<schedulerId>:<dueMillis>
 ```
 
-That id makes enqueueing idempotent — the same occurrence can never exist twice,
+That id makes enqueueing idempotent - the same occurrence can never exist twice,
 no matter how many workers or producers race to create it.
 
 The chain sustains itself: when a worker *first picks up* an occurrence, it
 mints the successor before running the handler. The schedule therefore stays on
 time regardless of how long the run takes, whether it fails, or how many retries
-follow — retries re-run *that occurrence*, they never shift the cadence. If the
+follow - retries re-run *that occurrence*, they never shift the cadence. If the
 scheduler was removed in the meantime, no successor is minted and the chain
 ends.
 
@@ -66,6 +66,6 @@ ends.
   and re-run ([Reliability](reliability.md)). Make handlers idempotent.
 - **No catch-up replay.** If every worker is down across several due times, the
   pending occurrence is promoted late and the next one lands on the current
-  grid/cron slot — you get *one* late run, not a burst of missed ones.
+  grid/cron slot - you get *one* late run, not a burst of missed ones.
 - **One pending occurrence per schedule** exists at a time (the deterministic id
   guarantees it), so a misbehaving schedule can't flood the queue.

toro_queue-0.3.0/docs/security.md

@@ -0,0 +1,38 @@
+# Security
+
+toro's security model in one sentence: **whoever can reach your Redis can do
+anything your queue can do** - so secure the Redis, and toro takes care of not
+amplifying that access.
+
+## What toro guarantees
+
+- **JSON-only serialization.** Job data, options, results and events are
+  `json` in and out - never pickle. A compromised or shared Redis cannot
+  achieve code execution through toro's deserialization.
+- **No dynamic dispatch from Redis.** A job's `name` is a label, not an import
+  path. The processor function is registered in your worker's code; nothing
+  read from Redis decides what code runs.
+- **No string-built commands.** Every state transition is a Lua script taking
+  ids and payloads as arguments (`KEYS[]`/`ARGV[]`), and every published event
+  is one `cjson.encode` document - there is no string interpolation into
+  commands or event JSON anywhere.
+- **Key-safe identifiers.** Custom job ids, scheduler ids and deduplication
+  ids are validated (no `:`, no control characters) so two logically distinct
+  ids can never collide into one Redis key.
+
+## What you own
+
+- **Redis access control.** Use a password (`requirepass`/ACLs), network
+  isolation, and `rediss://` URLs with a trusted CA for anything that crosses
+  a network boundary. For custom TLS options, build the connection yourself
+  and pass it as `connection=`.
+- **Secrets in job payloads and exceptions.** Payloads, return values, failure
+  reasons and stack traces are stored in Redis and visible to anything that
+  can read it (including dashboards). Don't put credentials in `data`, and
+  don't interpolate secrets into exception messages.
+- **Payload discipline.** toro does not enforce a payload size limit. Large
+  payloads cost memory in every worker that touches them - store big data
+  elsewhere (object storage) and enqueue a reference.
+- **Validate what you process.** Arriving as JSON doesn't make `job.data`
+  trustworthy if multiple producers share the queue; validate shape and
+  ranges in the handler like you would any external input.

toro_queue-0.3.0/examples/README.md

@@ -0,0 +1,19 @@
+# Examples
+
+Runnable, self-contained demos of toro. Each needs a Redis on `localhost:6379`:
+
+```bash
+docker run --rm -p 6379:6379 redis:7-alpine   # or any local Redis
+```
+
+Then run from the repo root:
+
+| Example | What it shows |
+|---|---|
+| [`basic.py`](basic.py) | The end-to-end loop - enqueue jobs (including a delayed one and a flaky one with `attempts` + exponential backoff), process them with a `concurrency=4` worker, and react to `completed` / `retrying` / `failed` events. |
+| [`stalled.py`](stalled.py) | Crash recovery - a "zombie" worker grabs a job and hangs; a healthy worker detects the stalled job, requeues it, and completes it **exactly once**. The zombie's late finish is rejected by its lock token. |
+
+```bash
+python examples/basic.py
+python examples/stalled.py
+```

{toro_queue-0.2.0 → toro_queue-0.3.0}/examples/stalled.py

@@ -1,4 +1,4 @@
-"""Demo: a worker dies mid-job and another recovers it — exactly one completion.
+"""Demo: a worker dies mid-job and another recovers it - exactly one completion.
 
 Run a Redis on localhost:6379, then:  python examples/stalled.py
 """
@@ -36,7 +36,7 @@ async def main():
     healthy.on("completed", lambda j, r: print(f"  ✓ #{j.id} completed by {r['by']}"))
     zombie.on(
         "lock-lost",
-        lambda jid: print(f"  [zombie] woke up, but #{jid} was taken — finish rejected"),
+        lambda jid: print(f"  [zombie] woke up, but #{jid} was taken - finish rejected"),
     )
 
     zt = asyncio.create_task(zombie.run())

{toro_queue-0.2.0 → toro_queue-0.3.0}/pyproject.toml

@@ -1,8 +1,8 @@
 [project]
-# PyPI distribution name — plain `toro` is taken (abandoned). The import package
+# 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.2.0"
+version = "0.3.0"
 description = "An async-first, Redis-backed job queue for Python."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -66,13 +66,13 @@ ignore = [
     "COM812", "ISC001",            # conflict with the formatter (per Ruff docs)
     "EM101", "EM102", "TRY003",    # inline exception messages read fine in this codebase
     "TRY300",                      # `else`-after-return reads worse than an early return here
-    "D203", "D213", "D205",        # docstring whitespace/placement niceties — not worth churn
+    "D203", "D213", "D205",        # docstring whitespace/placement niceties - not worth churn
     "D100", "D104", "D105", "D107", # don't require docstrings on modules/packages/dunder/__init__
     "ANN401",                      # `Any` is intentional at the Redis / JSON boundary
     "PLR2004",                     # small internal magic-number comparisons are clear in context
     "FBT001", "FBT002",            # boolean flags read fine in this API surface
     "D102",                        # docstrings on every public method is too granular here
-    "PLR0913",                     # Worker/Queue are config constructors — many kwargs is fine
+    "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
 ]
@@ -94,7 +94,7 @@ asyncio_mode = "auto"
 # `-m integration` (needs Redis), or `-m load` (slow). conftest auto-marks by folder.
 addopts = "--strict-markers --import-mode=importlib"
 markers = [
-    "unit: pure-logic tests, no I/O — fast and deterministic",
+    "unit: pure-logic tests, no I/O - fast and deterministic",
     "integration: Redis-backed tests of real state transitions",
     "load: throughput / scalability tests (slow; opt-in)",
 ]

{toro_queue-0.2.0 → toro_queue-0.3.0}/tests/conftest.py

@@ -109,14 +109,14 @@ async def _running_worker(queue: Queue, processor, **kw):
 
 @pytest.fixture
 def run_worker():
-    """`async with run_worker(q, processor, concurrency=2) as w: ...` — starts a
+    """`async with run_worker(q, processor, concurrency=2) as w: ...` - starts a
     worker and guarantees a clean shutdown on exit."""
     return _running_worker
 
 
 @pytest.fixture
 def run_until():
-    """`await run_until(lambda: cond, timeout=2)` — poll until true or time out.
+    """`await run_until(lambda: cond, timeout=2)` - poll until true or time out.
     Returns True if the condition held, False on timeout (assert on the result)."""
 
     async def _run_until(predicate, *, timeout: float = 5.0, interval: float = 0.02) -> bool:

{toro_queue-0.2.0 → toro_queue-0.3.0}/tests/integration/test_admin.py

@@ -1,4 +1,4 @@
-"""Integration: admin/dashboard actions — remove, promote, retry, clean, trigger.
+"""Integration: admin/dashboard actions - remove, promote, retry, clean, trigger.
 
 Each asserts the resulting state AND the negative case (acting on a missing job
 returns False rather than silently succeeding).
@@ -13,7 +13,7 @@ async def _count(q, state):
 
 @pytest.mark.parametrize("bad", ["", "a:b", "repeat:x", "ctrl\x01", "\n"])
 async def test_add_scheduler_rejects_unsafe_id(q, bad):
-    # scheduler_id is a Redis key segment — ':'/control chars enable key collisions
+    # scheduler_id is a Redis key segment - ':'/control chars enable key collisions
     with pytest.raises(ValueError, match="scheduler_id"):
         await q.add_scheduler(bad, cron="0 0 * * *")