localqueue 0.4.0__tar.gz → 0.4.1__tar.gz

{localqueue-0.4.0 → localqueue-0.4.1}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.4.1](https://github.com/brunoportis/localqueue/compare/v0.4.0...v0.4.1) (2026-04-25)
+
+
+### Documentation
+
+* reposition use cases and guides ([8e98379](https://github.com/brunoportis/localqueue/commit/8e98379c29091b414ad437facbdb4d7a7c45db4c))
+* reposition use cases and guides ([280288b](https://github.com/brunoportis/localqueue/commit/280288b02f877d78d2df067df67ce14a800cbfe2))
+* simplify queue examples ([ed488b2](https://github.com/brunoportis/localqueue/commit/ed488b2ab210369331fbcda3568760f0da24618b))
+* split use cases into dedicated pages ([5496826](https://github.com/brunoportis/localqueue/commit/54968266b0733b009147c56761ce9fe29889d5e9))
+
 ## [0.4.0](https://github.com/brunoportis/localqueue/compare/v0.3.4...v0.4.0) (2026-04-24)
 
 

{localqueue-0.4.0 → localqueue-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localqueue
-Version: 0.4.0
+Version: 0.4.1
 Summary: Durable local queues for Python, with persistent retry state powered by Tenacity.
 Project-URL: Homepage, https://brunoportis.github.io/localqueue/
 Project-URL: Documentation, https://brunoportis.github.io/localqueue/
@@ -40,9 +40,17 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://img.shields.io/pypi/v/localqueue.svg)](https://pypi.org/project/localqueue/)
 ![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
 
-`localqueue` is a small durable queue for one machine. It stores work on the local filesystem by default and keeps retry state with Tenacity.
+`localqueue` is a small durable queue for one machine. It stores work on the
+local filesystem by default and keeps retry state with Tenacity.
 
-Use it for scripts, CLI tools, cron jobs, and small Python workers that share one local store. Use `localqueue.retry` when another system already delivers work and you only need retry state that survives restarts.
+Use it when the work can stay local and you want one of these outcomes:
+
+- accept work now and perform the side effect later on the same machine
+- inspect failed jobs and replay them from the terminal
+- keep retry budgets across process restarts without adding a broker
+
+It fits scripts, CLI tools, cron jobs, and small Python workers that share one
+local store.
 
 ```bash
 localqueue queue exec emails -- python scripts/send_email.py
@@ -61,6 +69,9 @@ def send_email(job: dict[str, str]) -> None:
 
 Full docs live at [brunoportis.github.io/localqueue](https://brunoportis.github.io/localqueue/). The source docs are in [`docs/`](docs/).
 
+Start with [`docs/use-cases.md`](docs/use-cases.md) if you want the shortest
+path to deciding whether the project fits your workflow.
+
 For development and release workflow details, see [`docs/develop.md`](docs/develop.md).
 
 ## Install

{localqueue-0.4.0 → localqueue-0.4.1}/README.md

@@ -5,9 +5,17 @@
 [![PyPI version](https://img.shields.io/pypi/v/localqueue.svg)](https://pypi.org/project/localqueue/)
 ![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
 
-`localqueue` is a small durable queue for one machine. It stores work on the local filesystem by default and keeps retry state with Tenacity.
+`localqueue` is a small durable queue for one machine. It stores work on the
+local filesystem by default and keeps retry state with Tenacity.
 
-Use it for scripts, CLI tools, cron jobs, and small Python workers that share one local store. Use `localqueue.retry` when another system already delivers work and you only need retry state that survives restarts.
+Use it when the work can stay local and you want one of these outcomes:
+
+- accept work now and perform the side effect later on the same machine
+- inspect failed jobs and replay them from the terminal
+- keep retry budgets across process restarts without adding a broker
+
+It fits scripts, CLI tools, cron jobs, and small Python workers that share one
+local store.
 
 ```bash
 localqueue queue exec emails -- python scripts/send_email.py
@@ -26,6 +34,9 @@ def send_email(job: dict[str, str]) -> None:
 
 Full docs live at [brunoportis.github.io/localqueue](https://brunoportis.github.io/localqueue/). The source docs are in [`docs/`](docs/).
 
+Start with [`docs/use-cases.md`](docs/use-cases.md) if you want the shortest
+path to deciding whether the project fits your workflow.
+
 For development and release workflow details, see [`docs/develop.md`](docs/develop.md).
 
 ## Install

{localqueue-0.4.0 → localqueue-0.4.1}/docs/index.md

@@ -4,19 +4,30 @@ icon: lucide/inbox
 
 # Overview
 
-`localqueue` is a small durable queue for one machine. It stores work on the local filesystem by default and keeps retry state with Tenacity.
+`localqueue` is a small durable queue for one machine. It stores work on the
+local filesystem by default and keeps retry state with Tenacity.
 
-It fits scripts, CLI tools, cron jobs, development helpers, and small workers that can safely share one local store. It is not a distributed broker and does not provide multi-host coordination.
+It fits scripts, CLI tools, cron jobs, development helpers, and small workers
+that can safely share one local store. It is not a distributed broker and does
+not provide multi-host coordination.
 
 !!! note
     The default model is local-file storage, at-least-once delivery, and best-effort ordering under concurrency.
 
+## Best-fit workflows
+
+`localqueue` is strongest in three situations:
+
+- local outbox workflows where the caller should return before the side effect happens
+- terminal-driven recovery where operators need dead-letter inspection and replay
+- persistent retry budgets for work that already arrives from somewhere else
+
 ## CLI
 
 Use the CLI when you want to enqueue, inspect, watch, and recover jobs from the terminal.
 
 ```bash
-localqueue queue add emails --value '{"to":"user@example.com"}'
+echo '{"to":"user@example.com"}' | localqueue queue add emails
 localqueue queue exec emails -- python scripts/send_email.py
 localqueue queue stats emails --watch --interval 1
 localqueue queue dead emails --summary
@@ -42,14 +53,13 @@ def send_email(job: dict[str, str]) -> None:
     deliver(job["to"])
 ```
 
-`localqueue.retry` stays available when another system already delivers work and you only need retry state.
-
 See [Persistent retries](retries.md) for the retry API and store options.
 
 ## When to use
 
 - small Python workers on one machine
 - scripts that need durable work after restarts
+- local outbox workflows for emails, webhooks, uploads, or reports
 - terminal-driven queues for jobs you want to inspect and requeue
 - retry state that must survive process restarts
 

{localqueue-0.4.0 → localqueue-0.4.1}/docs/queues.md

@@ -4,14 +4,28 @@ icon: lucide/inbox
 
 # Persistent Queues
 
-`localqueue` is the main workflow API in this project. It is a small queue
-abstraction backed by SQLite by default and designed for durable, at-least-once
-delivery of Python values.
+`localqueue` queues are for local workflows where you want to accept work now,
+run it later on the same machine, and keep enough state to inspect and recover
+failures from the terminal.
+
+This is the main workflow API in the project. It is a small queue abstraction
+backed by SQLite by default and designed for durable, at-least-once delivery of
+Python values.
 
 It is local infrastructure: producers and consumers should run where they can
 share the same queue store safely. It is not a distributed broker and does not
 provide multi-host coordination.
 
+Best-fit queue workflows:
+
+- local outbox patterns for email, webhooks, uploads, or report generation
+- CLI-driven workers that should survive restarts
+- jobs that may need dead-letter inspection and replay
+
+Start somewhere else if the queue itself needs to be a distributed system
+boundary. `localqueue` keeps delivery local, recovery local, and operations
+simple.
+
 If you have independent workloads, give them separate queue names instead of
 loading everything into one queue. Each queue keeps its own stats, dead
 letters, retention settings, and worker identity history.
@@ -30,7 +44,8 @@ queue = PersistentQueue(
 )
 ```
 
-The queue name identifies an independent stream inside the store. Queue names cannot be empty and cannot contain `:`.
+The queue name identifies an independent stream inside the store. Queue names
+cannot be empty and cannot contain `:`.
 Queue-level retry defaults are merged into worker retry kwargs before explicit
 worker overrides, so the same policy can be reused across several workers that
 consume the same queue.

{localqueue-0.4.0 → localqueue-0.4.1}/docs/retries.md

@@ -4,14 +4,27 @@ icon: lucide/rotate-cw
 
 # Persistent Retries
 
-`localqueue` is the durable retry layer used by queue workers and by code
-that already has its own delivery mechanism. It wraps Tenacity's `Retrying` and
-`AsyncRetrying` classes. You still configure `stop`, `wait`, `retry`, callbacks,
-and `retry_with()` the same way; the wrapper adds a durable attempt record before
-each stop decision.
-
-If you need a full job lifecycle with ack, release, leases, and dead-letter
-records, start with [Persistent queues](queues.md).
+`localqueue.retry` is for code that already receives the work but still needs a
+retry budget that survives process restarts.
+
+This is the durable retry layer used by queue workers and by code that already
+has its own delivery mechanism. It wraps Tenacity's `Retrying` and
+`AsyncRetrying` classes. You still configure `stop`, `wait`, `retry`,
+callbacks, and `retry_with()` the same way; the wrapper adds a durable attempt
+record before each stop decision.
+
+Best-fit retry workflows:
+
+- cron jobs that call fragile external services
+- HTTP handlers or consumers that need durable retry budgets per logical job
+- scripts where retry state must outlive the current process
+
+Use this layer when the missing piece is persistent attempt tracking. If you
+need ack, release, leases, dead-letter records, or queue inspection, start with
+[Persistent queues](queues.md) instead.
+
+The main design constraint is stable identity: each logical job needs a stable
+retry key so the same work does not retry forever under a new process.
 
 ## Decorator API
 

localqueue-0.4.1/docs/use-cases/local-outbox.md

@@ -0,0 +1,83 @@
+---
+icon: lucide/mail
+---
+
+# Local Outbox
+
+Use this pattern when the caller should return now and the external side effect
+can happen a few seconds later on the same machine.
+
+This is one of the strongest `localqueue` stories: accept work quickly, store
+it durably, and let a local worker perform the slow or fragile side effect
+later.
+
+## Best fit
+
+- email delivery from a web app or admin script
+- webhook fan-out from a local integration process
+- uploads, report generation, or notifications that should not block the caller
+
+## Why `localqueue` fits
+
+- no broker, Redis, or extra service to operate
+- queue state survives process restarts
+- the worker can be a Python function or an external command
+
+## Boundaries
+
+- this is a single-host pattern, not a distributed outbox
+- delivery is at least once, so handlers should be idempotent
+
+## Setup
+
+Create a scratch directory and a small worker script once:
+
+```bash
+mkdir -p /tmp/localqueue-use-cases
+cat > /tmp/localqueue-use-cases/email_worker.py <<'PY'
+from __future__ import annotations
+
+import json
+import sys
+
+
+payload = json.load(sys.stdin)
+address = payload["to"]
+if payload.get("fail"):
+    raise ConnectionError(f"could not deliver email to {address}")
+print(f"sent email to {address}")
+PY
+```
+
+## Minimal flow
+
+Enqueue one email job:
+
+```bash
+echo '{"to":"user@example.com"}' | localqueue queue add emails
+```
+
+Inspect the queue before processing:
+
+```bash
+localqueue queue stats emails
+```
+
+Process one queued message with the worker script:
+
+```bash
+localqueue queue exec emails \
+  -- python /tmp/localqueue-use-cases/email_worker.py
+```
+
+Check that the queue is empty again:
+
+```bash
+localqueue queue stats emails
+```
+
+## When to choose something else
+
+Use a broker or managed queue instead when producers and consumers run on
+different machines, strict global ordering matters, or the queue is part of a
+distributed system boundary.

localqueue-0.4.1/docs/use-cases/operator-recovery.md

@@ -0,0 +1,85 @@
+---
+icon: lucide/life-buoy
+---
+
+# Operator Recovery
+
+Use this pattern when jobs can fail in recoverable ways and operators need to
+inspect, dead-letter, and replay them from the terminal.
+
+This is where `localqueue` feels more useful than a pile of shell scripts:
+failures stay visible, recovery is explicit, and replay does not require a
+custom one-off script.
+
+## Best fit
+
+- webhook delivery with occasional upstream outages
+- notification pipelines that need human inspection on failure
+- CLI-driven maintenance jobs where operators need a dead-letter queue
+
+## Why `localqueue` fits
+
+- failed jobs can move to dead-letter after a small retry budget
+- operators can inspect summary and full records locally
+- replay is one command instead of ad hoc recovery code
+
+## Boundaries
+
+- recovery is local to one machine and one shared store
+- this does not replace broker-level operations across multiple services
+
+## Setup
+
+Create a scratch directory and a small worker script once:
+
+```bash
+mkdir -p /tmp/localqueue-use-cases
+cat > /tmp/localqueue-use-cases/email_worker.py <<'PY'
+from __future__ import annotations
+
+import json
+import sys
+
+
+payload = json.load(sys.stdin)
+address = payload["to"]
+if payload.get("fail"):
+    raise ConnectionError(f"could not deliver email to {address}")
+print(f"sent email to {address}")
+PY
+```
+
+## Minimal flow
+
+Create a failing job:
+
+```bash
+echo '{"to":"broken@example.com","fail":true}' | localqueue queue add webhooks
+```
+
+Process it with a small retry budget so it reaches dead-letter quickly:
+
+```bash
+localqueue queue exec webhooks \
+  --max-tries 2 \
+  -- python /tmp/localqueue-use-cases/email_worker.py
+```
+
+Inspect the dead-letter summary and full record:
+
+```bash
+localqueue queue dead webhooks --summary
+
+localqueue queue dead webhooks
+```
+
+Replay everything in the dead-letter queue:
+
+```bash
+localqueue queue requeue-dead webhooks --all
+```
+
+## When to choose something else
+
+Use a different system when recovery, retention, and observability must work as
+shared platform capabilities across multiple hosts or services.

localqueue-0.4.1/docs/use-cases/persistent-retries.md

@@ -0,0 +1,74 @@
+---
+icon: lucide/rotate-cw
+---
+
+# Persistent Retries
+
+Use this pattern when another part of your system already delivers the work and
+the missing piece is a retry budget that survives process restarts.
+
+This page is about persistent attempt tracking, not a full queue lifecycle. If
+you need ack, release, leases, or dead-letter handling, start with
+`PersistentQueue` instead.
+
+## Best fit
+
+- cron jobs that call an external API
+- HTTP handlers that already receive the work but need durable retry budgets
+- consumers from another queueing system that want persistent retry state
+
+## Why `localqueue` fits
+
+- retry budgets survive process restarts
+- a stable key prevents the same logical job from being retried forever
+- exhausted jobs can be pruned later from the CLI
+
+## Boundaries
+
+- this is retry state, not a full message lifecycle
+- each logical job needs a stable retry key
+
+## Minimal flow
+
+Run this once in an environment where `localqueue` is importable.
+
+```bash
+python - <<'PY'
+from localqueue.retry import PersistentRetryExhausted, persistent_retry
+
+
+@persistent_retry(
+    key="invoice:1001",
+    max_tries=3,
+)
+def flaky() -> None:
+    print("calling remote API")
+    raise ConnectionError("temporary upstream failure")
+
+
+try:
+    flaky()
+except PersistentRetryExhausted as exc:
+    print(f"exhausted: {exc.key} after {exc.attempts} attempts")
+except Exception as exc:
+    print(f"failed this run: {exc}")
+PY
+```
+
+Run the same command again. The retry state is reused because the key is
+stable and the attempt store is on disk. After the budget is exhausted,
+`PersistentRetryExhausted` is raised before the wrapped function runs again.
+
+Inspect or prune exhausted retry records later:
+
+```bash
+localqueue retry prune \
+  --dry-run \
+  --older-than 0
+```
+
+## When to choose something else
+
+Use a queue instead when work must be stored for later delivery, acknowledged
+after success, released for another attempt, or moved to dead-letter on final
+failure.

localqueue-0.4.1/docs/use-cases.md

@@ -0,0 +1,54 @@
+---
+icon: lucide/briefcase
+---
+
+# Use Cases
+
+`localqueue` shines when the work can stay on one machine and the value is in
+durable retries, local recovery, and simple terminal operations.
+
+The pages in this section focus on workflows that are already well supported by
+the current queue, worker, dead-letter, and persistent-retry APIs.
+
+By default, `localqueue` stores queue and retry state under the usual XDG data
+location for your user.
+
+## The three strongest workflows
+
+### Local outbox
+
+Accept work now, run the external side effect later on the same machine.
+
+This is the best fit when the caller should return quickly and the worker can
+consume the job from a shared local store.
+
+[Read the local outbox guide](use-cases/local-outbox.md)
+
+### Operator recovery
+
+Inspect failed jobs, review dead-letter records, and replay them from the
+terminal after the underlying issue is fixed.
+
+This is the best fit when a human operator needs a local recovery loop instead
+of ad hoc shell scripts.
+
+[Read the operator recovery guide](use-cases/operator-recovery.md)
+
+### Persistent retries
+
+Keep retry budgets across restarts when another part of the system already
+delivers the work.
+
+This is the best fit when you need durable attempt tracking but not a queue
+lifecycle.
+
+[Read the persistent retries guide](use-cases/persistent-retries.md)
+
+## When these use cases do not fit
+
+Use a broker or managed queue instead when:
+
+- producers and consumers run on different machines
+- strict global ordering matters
+- very high write concurrency is expected
+- queue retention, fan-out, or cross-service coordination is a first-class need

{localqueue-0.4.0 → localqueue-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "localqueue"
-version = "0.4.0"
+version = "0.4.1"
 description = "Durable local queues for Python, with persistent retry state powered by Tenacity."
 readme = "README.md"
 requires-python = ">=3.11"

{localqueue-0.4.0 → localqueue-0.4.1}/uv.lock

@@ -200,7 +200,7 @@ wheels = [
 
 [[package]]
 name = "localqueue"
-version = "0.4.0"
+version = "0.4.1"
 source = { editable = "." }
 dependencies = [
     { name = "tenacity" },

localqueue-0.4.0/docs/use-cases.md

@@ -1,174 +0,0 @@
----
-icon: lucide/briefcase
----
-
-# Use Cases
-
-These examples are meant to be copied and run from any directory.
-They keep state under `/tmp/localqueue-use-cases` so they do not interfere with
-your normal localqueue data.
-
-## Command style
-
-The examples below use the direct CLI form:
-
-```bash
-localqueue queue exec ...
-```
-
-Install `localqueue[cli]` first if the `localqueue` command is not available.
-If you prefer `pipx run` or `uvx`, translate the command locally after you
-understand the workflow.
-
-## Setup
-
-Create a scratch directory and a small worker script once:
-
-```bash
-mkdir -p /tmp/localqueue-use-cases
-cat > /tmp/localqueue-use-cases/email_worker.py <<'PY'
-from __future__ import annotations
-
-import json
-import sys
-
-
-payload = json.load(sys.stdin)
-address = payload["to"]
-if payload.get("fail"):
-    raise ConnectionError(f"could not deliver email to {address}")
-print(f"sent email to {address}")
-PY
-```
-
-## 1. Local email spooler
-
-This is the simplest shape for `localqueue`: one process enqueues work and
-another process handles it later on the same machine.
-
-Enqueue one email job:
-
-```bash
-localqueue queue add emails \
-  --store-path /tmp/localqueue-use-cases/emails.sqlite3 \
-  --value '{"to":"user@example.com"}'
-```
-
-Inspect the queue before processing:
-
-```bash
-localqueue queue stats emails \
-  --store-path /tmp/localqueue-use-cases/emails.sqlite3
-```
-
-Process one queued message with the worker script:
-
-```bash
-localqueue queue exec emails \
-  --store-path /tmp/localqueue-use-cases/emails.sqlite3 \
-  -- python /tmp/localqueue-use-cases/email_worker.py
-```
-
-Check that the queue is empty again:
-
-```bash
-localqueue queue stats emails \
-  --store-path /tmp/localqueue-use-cases/emails.sqlite3
-```
-
-Use this pattern when your app should accept work quickly and let a local
-worker perform the external side effect later.
-
-## 2. Dead-letter and recover a failed command
-
-This recipe shows a practical operator loop: enqueue a job that fails, inspect
-the dead-letter list, then requeue it after fixing the payload.
-
-Create a failing job:
-
-```bash
-localqueue queue add emails \
-  --store-path /tmp/localqueue-use-cases/failing-emails.sqlite3 \
-  --value '{"to":"broken@example.com","fail":true}'
-```
-
-Process it with a small retry budget so it reaches dead-letter quickly:
-
-```bash
-localqueue queue exec emails \
-  --store-path /tmp/localqueue-use-cases/failing-emails.sqlite3 \
-  --retry-store-path /tmp/localqueue-use-cases/failing-emails-retries.sqlite3 \
-  --max-tries 2 \
-  -- python /tmp/localqueue-use-cases/email_worker.py
-```
-
-Inspect the dead-letter summary and full record:
-
-```bash
-localqueue queue dead emails \
-  --store-path /tmp/localqueue-use-cases/failing-emails.sqlite3 \
-  --summary
-
-localqueue queue dead emails \
-  --store-path /tmp/localqueue-use-cases/failing-emails.sqlite3
-```
-
-If you want to replay everything in the dead-letter queue:
-
-```bash
-localqueue queue requeue-dead emails \
-  --store-path /tmp/localqueue-use-cases/failing-emails.sqlite3 \
-  --all
-```
-
-This is a good fit for webhook delivery, notification pipelines, and other
-single-host jobs where operators need to inspect and replay failed work from
-the terminal.
-
-## 3. Persistent retries without a queue
-
-Sometimes another system already delivers the job and all you need is retry
-state that survives restarts. In that case, use `localqueue.retry` directly.
-
-Run this once in an environment where `localqueue` is importable.
-
-```bash
-python - <<'PY'
-from localqueue.retry import PersistentRetryExhausted, persistent_retry
-
-
-@persistent_retry(
-    key="invoice:1001",
-    store_path="/tmp/localqueue-use-cases/retries.sqlite3",
-    max_tries=3,
-)
-def flaky() -> None:
-    print("calling remote API")
-    raise ConnectionError("temporary upstream failure")
-
-
-try:
-    flaky()
-except PersistentRetryExhausted as exc:
-    print(f"exhausted: {exc.key} after {exc.attempts} attempts")
-except Exception as exc:
-    print(f"failed this run: {exc}")
-PY
-```
-
-Run the same command again. The retry state is reused because the key is
-stable and the attempt store is on disk. After the budget is exhausted,
-`PersistentRetryExhausted` is raised before the wrapped function runs again.
-
-You can later inspect or prune exhausted retry records:
-
-```bash
-localqueue retry prune \
-  --retry-store-path /tmp/localqueue-use-cases/retries.sqlite3 \
-  --dry-run \
-  --older-than 0
-```
-
-Use this shape when work already arrives from somewhere else, such as a cron
-trigger, another queue, or an HTTP handler, and you only want durable retry
-budgets.