localqueue 0.3.3__tar.gz → 0.4.0__tar.gz

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

@@ -1,5 +1,34 @@
 # Changelog
 
+## [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.
+- Preserve the batch empty-queue exit behavior for non-forever workers.
+
 ## 0.3.3
 
 - Split queue and retry store implementations into dedicated modules.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localqueue
-Version: 0.3.3
+Version: 0.4.0
 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/
@@ -61,6 +61,8 @@ 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/).
 
+For development and release workflow details, see [`docs/develop.md`](docs/develop.md).
+
 ## Install
 
 ```bash

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

@@ -26,6 +26,8 @@ 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/).
 
+For development and release workflow details, see [`docs/develop.md`](docs/develop.md).
+
 ## Install
 
 ```bash

localqueue-0.4.0/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.3 → localqueue-0.4.0}/docs/index.md

@@ -65,10 +65,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.4.0/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.4.0/docs/use-cases.md

@@ -0,0 +1,174 @@
+---
+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.

{localqueue-0.3.3 → localqueue-0.4.0}/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.3 → localqueue-0.4.0}/localqueue/services/queue_worker.py

@@ -352,6 +352,8 @@ def process_queue_messages(
                 )
             )
             if empty_queue:
+                if options.forever and options.block:
+                    continue
                 return handle_empty_queue(err_console, processed)
             assert iteration is not None
             if handle_processed_queue_result(

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

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

{localqueue-0.3.3 → localqueue-0.4.0}/tests/test_cli.py

@@ -58,6 +58,7 @@ from localqueue.cli_worker_commands import (
 )
 from localqueue.services.queue_worker import (
     QueueIterationContext as _QueueIterationContext,
+    QueueIterationResult as _QueueIterationResult,
     QueueWorkerOptions as _QueueWorkerOptions,
     _CommandExecutionError,
     _CommandNotFoundError,
@@ -214,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("{}"), "{}")
 
@@ -1747,6 +1755,55 @@ class CliTests(unittest.TestCase):
         self.assertEqual(console.values, [])
         self.assertEqual(err_console.messages, ["[yellow]queue is empty[/yellow]"])
 
+    def test_process_queue_messages_keeps_waiting_when_forever_blocking_is_empty(
+        self,
+    ) -> None:
+        queue = PersistentQueue("emails", store=MemoryQueueStore())
+        console = _JsonConsole()
+        err_console = _JsonConsole()
+        shutdown = _ShutdownState()
+
+        def stop_after_second_poll(
+            context: _QueueIterationContext,
+        ) -> tuple[_QueueIterationResult | None, SQLiteAttemptStore | None, bool]:
+            if shutdown.requested:
+                return None, None, True
+            shutdown.requested = True
+            self.assertTrue(context.forever)
+            self.assertTrue(context.block)
+            return None, None, True
+
+        with mock.patch(
+            "localqueue.services.queue_worker.process_queue_iteration",
+            side_effect=stop_after_second_poll,
+        ) as process_iteration:
+            result = _process_queue_messages(
+                queue,
+                lambda payload: payload,
+                console=console,
+                err_console=err_console,
+                shutdown=shutdown,
+                options=_QueueWorkerOptions(
+                    retry_store_path=self._retry_store_path(),
+                    max_jobs=1,
+                    forever=True,
+                    max_tries=1,
+                    worker_id="worker-a",
+                    block=True,
+                    timeout=None,
+                    idle_sleep=0.001,
+                    release_delay=0.0,
+                    dead_letter_on_exhaustion=True,
+                    log_events=False,
+                    mode="process",
+                ),
+            )
+
+        self.assertEqual(result, 0)
+        self.assertEqual(console.values, [{"state": "stopped", "processed": 0}])
+        self.assertEqual(err_console.messages, [])
+        self.assertEqual(process_iteration.call_count, 1)
+
     def test_process_queue_iteration_handles_forever_empty_queue_without_blocking(
         self,
     ) -> None:

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

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

localqueue-0.3.3/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.3`.