localqueue 0.3.4__tar.gz → 0.4.1__tar.gz

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

@@ -1,5 +1,39 @@
 # 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)
+
+
+### Features
+
+* add release-please automation and CLI --version option ([f8db976](https://github.com/brunoportis/localqueue/commit/f8db9767f45fc1eb5055ef0e7eb946aae3af3129))
+
+
+### Bug Fixes
+
+* **release:** target uv.lock version explicitly ([3e71f44](https://github.com/brunoportis/localqueue/commit/3e71f4450e50de69488b18c04b018a6af00bf962))
+* **release:** target uv.lock version explicitly ([31b45ce](https://github.com/brunoportis/localqueue/commit/31b45ce2ba3deea070d8d49c8bebebadcbc9fb37))
+* **release:** track uv.lock in release-please ([897b86a](https://github.com/brunoportis/localqueue/commit/897b86aa33d9b38cba82da7b0e2623473488b94d))
+* **release:** track uv.lock in release-please ([637ef7f](https://github.com/brunoportis/localqueue/commit/637ef7fca945f1153b643f27b0d6df6ccc39f778))
+* **workflow:** configure git identity for release sync ([9872e7a](https://github.com/brunoportis/localqueue/commit/9872e7a85d1382a968f344444009e721da926e50))
+* **workflow:** configure git identity for release sync ([2ef15fd](https://github.com/brunoportis/localqueue/commit/2ef15fdd3b5a877569b46980ef795442c1f3089c))
+* **workflow:** sync uv.lock in release-please ([f26b1fa](https://github.com/brunoportis/localqueue/commit/f26b1fac2603f5ae0016ce994f5065291b6a6ad0))
+* **workflow:** sync uv.lock in release-please ([193b4c6](https://github.com/brunoportis/localqueue/commit/193b4c6d5dba208ec43d7ea6ada402c5c4f1c2a5))
+
+
+### Documentation
+
+* **use-cases:** simplify CLI examples ([84b92f2](https://github.com/brunoportis/localqueue/commit/84b92f2a420ddeb46dc8db2e6c1493fc45430bff))
+
 ## 0.3.4
 
 - Keep `queue exec` and `queue process` alive in `--forever --block` mode when the queue starts empty.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localqueue
-Version: 0.3.4
+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,11 @@ 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
 
 ```bash

{localqueue-0.3.4 → 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,11 @@ 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
 
 ```bash

localqueue-0.4.1/docs/develop.md

@@ -0,0 +1,137 @@
+---
+icon: lucide/hammer
+---
+
+# Development Guide
+
+This page describes the day-to-day development flow for `localqueue`: how to
+write commits, how versions are released, what quality gates should pass before
+merging, and what happens to docs and deployments.
+
+## Commit style
+
+Use Conventional Commits.
+
+Preferred shapes:
+
+```text
+feat: add queue health summary
+fix: keep forever workers alive on empty queues
+docs: describe release flow
+chore: refresh release-please config
+test: cover version output in the CLI
+```
+
+Keep commit messages short and specific. Use a scope only when it helps the
+history, for example `fix(cli): ...` or `docs(release): ...`.
+
+Why this matters here:
+
+- `release-please` uses commit history to decide the next version.
+- clean commit messages produce cleaner changelogs.
+- release PRs become easier to review when each change has a clear intent.
+
+## Versioning
+
+Versions follow SemVer-style `MAJOR.MINOR.PATCH`.
+
+Before `1.0.0`, use this rule:
+
+| Change | Version bump |
+| --- | --- |
+| Bug fix only | patch |
+| New CLI/API feature | minor |
+| Breaking user-facing behavior | minor, with a clear changelog note |
+
+In this repo:
+
+- `release-please` opens or updates the release PR.
+- merging that release PR creates the tag and the GitHub Release.
+- the release tag stays in the form `v<version>`.
+- `pyproject.toml` is updated by the release automation, not by hand.
+
+## Quality gates before merge
+
+Run the project checks before opening or merging a release-worthy change.
+
+```bash
+env UV_CACHE_DIR=/tmp/uv-cache uv run ruff format .
+env UV_CACHE_DIR=/tmp/uv-cache uv run ruff format --check .
+env UV_CACHE_DIR=/tmp/uv-cache uv run pytest -q
+env UV_CACHE_DIR=/tmp/uv-cache uv run ruff check .
+env UV_CACHE_DIR=/tmp/uv-cache uv run basedpyright
+env UV_CACHE_DIR=/tmp/uv-cache uv run zensical build --clean
+env UV_CACHE_DIR=/tmp/uv-cache uv lock --check
+env UV_CACHE_DIR=/tmp/uv-cache uv build
+```
+
+Practical notes:
+
+- `pytest` is the main behavior gate.
+- `ruff format` applies the formatting fix locally.
+- `ruff format --check` verifies formatting stays stable before a merge.
+- `ruff check` and `basedpyright` keep the codebase clean and typed where it
+  matters.
+- `zensical build --clean` catches docs breakage before it lands.
+- `uv lock --check` confirms the lockfile is current.
+- `uv build` verifies the package artifacts still build cleanly.
+
+## Documentation workflow
+
+Docs should stay close to the code and the release flow.
+
+- Update `docs/` when the CLI, public API, or release process changes.
+- Keep `docs/release.md` focused on release automation and tagging.
+- Keep `docs/operational-maturity.md` focused on runtime guarantees and
+  production boundaries.
+- Update `docs/index.md` and the docs navigation when a new top-level doc is
+  added.
+
+Good documentation changes usually include:
+
+- a short user-facing description
+- exact commands
+- concrete examples
+- the current expected release or deployment behavior
+
+## Deployments
+
+The docs site is built from `docs/` with `zensical`.
+
+The release workflow currently handles:
+
+- PyPI publication
+- GHCR image publication
+
+The docs workflow currently handles:
+
+- building the docs site on pushes and pull requests
+- deploying the site from GitHub Actions on push to the configured branches
+
+If a change affects packaging, release tags, or public docs, validate both the
+package build and the docs build before merging.
+
+## Local release checklist
+
+When preparing a release or release PR, verify:
+
+1. commits follow Conventional Commits
+2. tests pass
+3. lint and typecheck pass
+4. docs build
+5. package build succeeds
+6. the release notes and changelog reflect the change
+
+## Secrets and CI
+
+The current release automation expects:
+
+- `RELEASE_PLEASE_TOKEN` for `release-please`
+- `SONAR_TOKEN` for SonarCloud, if the Sonar workflow is enabled
+
+Keep secrets in repository settings, not in the repo.
+
+## Daily rule
+
+If a change would confuse the next release PR, fix the commit message, docs, or
+tests before merging it.

{localqueue-0.3.4 → 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
 
@@ -65,10 +75,12 @@ See [Compare](compare.md) for a short decision guide.
 
 ## Read more
 
+- [Use cases](use-cases.md)
 - [Persistent queues](queues.md)
 - [Persistent retries](retries.md)
 - [Stability](stability.md)
 - [Compare](compare.md)
 - [API reference](api.md)
 - [Operational maturity](operational-maturity.md)
+- [Development guide](develop.md)
 - [Release checklist](release.md)

{localqueue-0.3.4 → 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.1/docs/release.md

@@ -0,0 +1,47 @@
+---
+icon: lucide/package-check
+---
+
+# Release
+
+This project uses `release-please` to automate release PRs, changelog updates,
+version bumps, Git tags, and GitHub Releases. The PyPI and GHCR publication
+still happens in the existing release workflow after the release tag is
+created.
+
+## Versioning
+
+Use SemVer-style versions:
+
+```text
+MAJOR.MINOR.PATCH
+```
+
+Before `1.0.0`, use this convention:
+
+| Change | Version bump |
+| --- | --- |
+| Bug fix only | patch, for example `0.1.1` |
+| New CLI/API feature | minor, for example `0.2.0` |
+| Breaking user-facing behavior | minor before `1.0.0`, with a clear changelog note |
+
+## How it works
+
+1. Merge Conventional Commit changes into `master`.
+2. `release-please` opens or updates a release PR with the changelog and the
+   version bump.
+3. Merge the release PR.
+4. `release-please` tags the merge commit and creates the GitHub Release.
+5. The existing `Release` workflow publishes the artifacts to PyPI and GHCR.
+
+## Setup notes
+
+1. The workflow expects a repository secret named `RELEASE_PLEASE_TOKEN`.
+2. The release tag format stays `v<version>` so the current publish workflow can
+   keep matching `v*` tags.
+3. Keep commit messages in Conventional Commit form so `release-please` can
+   classify changes correctly.
+
+## Current Release
+
+The current planned release is `0.3.4`.

{localqueue-0.3.4 → 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.3.4 → localqueue-0.4.1}/localqueue/cli.py

@@ -8,6 +8,7 @@ from contextlib import contextmanager
 from pathlib import Path
 from typing import Any, Iterator, TYPE_CHECKING
 
+from . import __version__
 from .cli_commands import (
     CommandRegistryContext,
     register_config_commands,
@@ -75,6 +76,15 @@ def _build_app(typer: Any, yaml: Any, console: Any, err_console: Any) -> Any:
     queue_app = typer.Typer(no_args_is_help=True)
     retry_app = typer.Typer(no_args_is_help=True)
     config_app = typer.Typer(no_args_is_help=True)
+
+    @app.callback(invoke_without_command=True)
+    def root_callback(
+        version: bool = typer.Option(False, "--version", help="Show version and exit"),
+    ) -> None:
+        if version:
+            console.print(__version__)
+            raise typer.Exit()
+
     command_context = CommandRegistryContext(
         typer=typer,
         console=console,

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

@@ -1,6 +1,6 @@
 [project]
 name = "localqueue"
-version = "0.3.4"
+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.3.4 → localqueue-0.4.1}/tests/test_cli.py

@@ -215,6 +215,13 @@ class CliTests(unittest.TestCase):
         build_app.assert_called_once()
         app.assert_called_once_with(args=["--help"])
 
+    def test_root_version_option_prints_version(self) -> None:
+        with mock.patch("localqueue.cli.__version__", "9.9.9"):
+            result = self._invoke(["--version"])
+
+        self.assertEqual(result.exit_code, 0)
+        self.assertEqual(result.stdout.strip(), "9.9.9")
+
     def test_read_value_uses_argument_before_stdin(self) -> None:
         self.assertEqual(_read_value("{}"), "{}")
 

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

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

localqueue-0.3.4/docs/release.md

@@ -1,111 +0,0 @@
----
-icon: lucide/package-check
----
-
-# Release
-
-This project currently uses a manual versioning flow. The release version lives
-in `pyproject.toml`, and each release should have a matching `CHANGELOG.md`
-entry and Git tag.
-
-## Versioning
-
-Use SemVer-style versions:
-
-```text
-MAJOR.MINOR.PATCH
-```
-
-Before `1.0.0`, use this convention:
-
-| Change | Version bump |
-| --- | --- |
-| Bug fix only | patch, for example `0.1.1` |
-| New CLI/API feature | minor, for example `0.2.0` |
-| Breaking user-facing behavior | minor before `1.0.0`, with a clear changelog note |
-
-## Checklist
-
-1. Update `version` in `pyproject.toml`.
-2. Run `uv lock` and commit the updated `uv.lock`.
-3. Update `CHANGELOG.md`.
-4. Confirm `requires-python`, license metadata, and PyPI classifiers still match
-   supported Python versions and the intended release policy.
-5. Run the test suite:
-
-   ```bash
-   uv run pytest
-   ```
-
-6. Run lint and typecheck:
-
-   ```bash
-   uv run ruff check .
-   uv run basedpyright
-   ```
-
-7. Build the docs:
-
-   ```bash
-   uv run zensical build --clean
-   ```
-
-8. Confirm the lockfile is current:
-
-   ```bash
-   uv lock --check
-   ```
-
-9. Build the release artifacts:
-
-   ```bash
-   uv build
-   ```
-
-10. Inspect the artifacts:
-
-   ```bash
-   tar -tzf dist/localqueue-<version>.tar.gz | less
-   python -m zipfile -l dist/localqueue-<version>-py3-none-any.whl
-   ```
-
-11. Install the wheel in a clean virtual environment:
-
-   ```bash
-   uv venv /tmp/localqueue-release-venv
-   uv pip install --python /tmp/localqueue-release-venv/bin/python \
-     "dist/localqueue-<version>-py3-none-any.whl[all]"
-   /tmp/localqueue-release-venv/bin/localqueue --help
-   ```
-
-12. Run a local smoke test:
-
-    ```bash
-    uv run python examples/enqueue_email.py user@example.com \
-      --store-path /tmp/localqueue-smoke
-
-    uv run localqueue queue process emails examples.email_worker:send_email \
-      --store-path /tmp/localqueue-smoke \
-      --retry-store-path /tmp/localqueue-smoke-retries.sqlite3 \
-      --worker-id worker-smoke \
-      --max-tries 3
-    ```
-
-13. Create the release tag:
-
-    ```bash
-    git tag v<version>
-    ```
-
-14. Publish the artifacts.
-
-    This release workflow also publishes the CLI image to GitHub Container
-    Registry as `ghcr.io/brunoportis/localqueue:<tag>` and `:latest`.
-
-15. Confirm the docs deployment finished successfully in the `Documentation`
-    workflow. GitHub Pages must be configured to deploy from GitHub Actions in
-    the repository settings.
-
-## Current Release
-
-The current planned release is `0.3.4`.