queueio 0.6.0__tar.gz → 0.8.0__tar.gz

{queueio-0.6.0 → queueio-0.8.0}/.devcontainer/docker-compose.yml

@@ -6,5 +6,8 @@ services:
     command: sleep infinity
   rabbitmq:
     image: rabbitmq:management
+    environment:
+      RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS: "-rabbit permit_deprecated_features #{global_qos=>true}"
     ports:
-      - 15672:15672
+      - 127.0.0.1:5672:5672
+      - 15672:15672

queueio-0.8.0/.github/workflows/build.yml

@@ -0,0 +1,92 @@
+name: Build
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      id-token: write
+    services:
+      rabbitmq:
+        image: rabbitmq
+        env:
+          RABBITMQ_DEFAULT_USER: guest
+          RABBITMQ_DEFAULT_PASS: guest
+          RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS: "-rabbit permit_deprecated_features #{global_qos=>true}"
+        ports:
+          - 5672/tcp
+        options: >-
+          --health-cmd "rabbitmq-diagnostics -q ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      rabbitmq_no_global_qos:
+        image: rabbitmq
+        env:
+          RABBITMQ_DEFAULT_USER: guest
+          RABBITMQ_DEFAULT_PASS: guest
+          RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS: "-rabbit permit_deprecated_features #{global_qos=>false}"
+        ports:
+          - 5672/tcp
+        options: >-
+          --health-cmd "rabbitmq-diagnostics -q ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      lavinmq:
+        # 2.10.3 and later starve consumers sharing a channel with global prefetch.
+        # https://github.com/cloudamqp/lavinmq/issues/2628
+        image: cloudamqp/lavinmq:2.10.2
+        ports:
+          - 5672/tcp
+        options: >-
+          --health-cmd "lavinmqctl status"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Set up Python
+        run: uv python install 3.15t
+      - name: Install dependencies
+        run: uv sync --all-groups
+      - name: Check formatting
+        run: uv run ruff format --check
+      - name: Run ruff linting
+        run: uv run ruff check
+      - name: Run basedpyright
+        run: uv run basedpyright
+      - name: Run tests
+        env:
+          QUEUEIO_BROKER: amqp://guest:guest@localhost:${{ job.services.rabbitmq.ports['5672'] }}/
+        run: uv run pytest --cov --cov-report=
+        timeout-minutes: 2
+      - name: Test broker without channel-wide QoS
+        env:
+          QUEUEIO_BROKER: amqp://guest:guest@localhost:${{ job.services.rabbitmq_no_global_qos.ports['5672'] }}/
+        run: uv run pytest -m no_global_qos --cov --cov-append --cov-report=
+      - name: Test LavinMQ
+        env:
+          QUEUEIO_BROKER: amqp://guest:guest@localhost:${{ job.services.lavinmq.ports['5672'] }}/
+        run: uv run pytest --cov --cov-append --cov-report=
+        timeout-minutes: 2
+      - name: Report coverage
+        run: |
+          uv run coverage report
+          uv run coverage xml
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          disable_search: true
+          use_oidc: true
+          fail_ci_if_error: true
+      - name: Verify built package
+        run: |
+          uv build
+          uvx --from dist/queueio-*.whl queueio --help

{queueio-0.6.0 → queueio-0.8.0}/.github/workflows/docs.yml

@@ -21,7 +21,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v5
-      - run: uv python install 3.14t
+      - run: uv python install 3.15t
       - run: uv sync --group dev
       - run: uv run mkdocs build --strict
       - uses: actions/upload-pages-artifact@v3

{queueio-0.6.0 → queueio-0.8.0}/.gitignore

@@ -6,6 +6,8 @@ dist/
 wheels/
 *.egg-info
 .coverage*
+coverage.xml
+htmlcov/
 
 # Virtual environments
 .venv

{queueio-0.6.0 → queueio-0.8.0}/CHANGELOG.md

@@ -8,6 +8,43 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com).
 [Unreleased]
 ------------
 
+[0.8.0] - 2026-11-04
+--------------------
+
+### Breaking Changes
+
+- Python 3.15 or later is now required; Python 3.14 is no longer supported.
+
+### Changed
+
+- Load the monitor UI lazily so other CLI commands avoid importing Textual.
+- Use [noio](https://pypi.org/project/noio/) for internal queues and selection,
+  replacing `queueio.queue` and `queueio.select`.
+
+### Fixed
+
+- A failed connection to the broker no longer leaves a thread running
+  that prevents the process from exiting.
+
+[0.7.0] - 2026-03-09
+--------------------
+
+### Breaking Changes
+
+- The `pika` configuration key in `[tool.queueio]` has been renamed to `broker`.
+- The `QUEUEIO_PIKA` environment variable has been renamed to `QUEUEIO_BROKER`.
+- Removed `Broker.create(queue)`, in favor of `Broker.sync([queue])`.
+- Removed `Broker.delete(queue)`, without replacement.
+- Removed `QueueIO.create(queue)`, in favor of `QueueIO.sync([queue])`.
+- Removed `QueueIO.delete(queue)`, without replacement.
+
+### Added
+
+- Added `Broker.sync()` to back `queueio sync`.
+- Added `QueueIO.sync()` to back `queueio sync`.
+- `Backend` ABC with `broker()` and `journal()` methods
+  that return independent context managers with their own lifecycles.
+
 [0.6.0] - 2026-02-16
 --------------------
 
@@ -106,7 +143,9 @@ Thank you to Nick Anderegg for allowing me to use the queueio name for this proj
 - The queuespec syntax to `queue run` to consume multiple queues with shared capacity.
 - `queueio monitor` command to monitor activity in the queueio system.
 
-[Unreleased]: https://github.com/ryanhiebert/queueio/compare/tag/0.6.0...HEAD
+[Unreleased]: https://github.com/ryanhiebert/queueio/compare/tag/0.8.0...HEAD
+[0.8.0]: https://github.com/ryanhiebert/queueio/compare/tag/0.7.0...tag/0.8.0
+[0.7.0]: https://github.com/ryanhiebert/queueio/compare/tag/0.6.0...tag/0.7.0
 [0.6.0]: https://github.com/ryanhiebert/queueio/compare/tag/0.5.0...tag/0.6.0
 [0.5.0]: https://github.com/ryanhiebert/queueio/compare/tag/0.4.0...tag/0.5.0
 [0.4.0]: https://github.com/ryanhiebert/queueio/compare/tag/0.3.0...tag/0.4.0

{queueio-0.6.0 → queueio-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: queueio
-Version: 0.6.0
+Version: 0.8.0
 Summary: Python background queues with an async twist
 Author-email: Ryan Hiebert <ryan@ryanhiebert.com>
 License-Expression: MIT
@@ -10,17 +10,20 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Distributed Computing
-Requires-Python: >=3.14
+Requires-Python: >=3.15
 Requires-Dist: dill>=0.3.9
+Requires-Dist: noio>=0.3
 Requires-Dist: pika>=1.3.2
 Requires-Dist: textual>=3.2.0
 Requires-Dist: typer>=0.15.4
 Provides-Extra: django
 Requires-Dist: django-cmd>=3.0; extra == 'django'
 Requires-Dist: django>=6.0; extra == 'django'
+Provides-Extra: psycopg
+Requires-Dist: psycopg>=3.3; extra == 'psycopg'
 Description-Content-Type: text/markdown
 
 ![queueio](https://raw.githubusercontent.com/ryanhiebert/queueio/main/logo.svg)
@@ -71,17 +74,25 @@ Add the configuration to your `pyproject.toml`:
 
 ```toml
 [tool.queueio]
-# Configure RabbitMQ
-pika = "amqp://guest:guest@localhost:5672/"
+# Configure the broker (currently supports amqp:// URIs)
+broker = "amqp://guest:guest@localhost:5672/"
 # Register the modules that the worker should load to find your routines
 register = ["basic"]
 ```
 
-The pika configuration can be overridden with an environment variable
+The broker configuration can be overridden with an environment variable
 to allow a project to be deployed in multiple environments.
 
 ```sh
-QUEUEIO_PIKA='amqp://guest:guest@localhost:5672/'
+QUEUEIO_BROKER='amqp://guest:guest@localhost:5672/'
+```
+
+QueueIO requires RabbitMQ's global QoS for shared concurrency limits and
+suspending tasks. On RabbitMQ 4.3, enable it in `rabbitmq.conf` and restart
+the broker:
+
+```ini
+deprecated_features.permit.global_qos = true
 ```
 
 Sync the queues to the broker:

{queueio-0.6.0 → queueio-0.8.0}/README.md

@@ -46,17 +46,25 @@ Add the configuration to your `pyproject.toml`:
 
 ```toml
 [tool.queueio]
-# Configure RabbitMQ
-pika = "amqp://guest:guest@localhost:5672/"
+# Configure the broker (currently supports amqp:// URIs)
+broker = "amqp://guest:guest@localhost:5672/"
 # Register the modules that the worker should load to find your routines
 register = ["basic"]
 ```
 
-The pika configuration can be overridden with an environment variable
+The broker configuration can be overridden with an environment variable
 to allow a project to be deployed in multiple environments.
 
 ```sh
-QUEUEIO_PIKA='amqp://guest:guest@localhost:5672/'
+QUEUEIO_BROKER='amqp://guest:guest@localhost:5672/'
+```
+
+QueueIO requires RabbitMQ's global QoS for shared concurrency limits and
+suspending tasks. On RabbitMQ 4.3, enable it in `rabbitmq.conf` and restart
+the broker:
+
+```ini
+deprecated_features.permit.global_qos = true
 ```
 
 Sync the queues to the broker:

{queueio-0.6.0 → queueio-0.8.0}/mkdocs.yml

@@ -37,5 +37,5 @@ nav:
   - Invocation: queueio/invocation.md
   - QueueSpec: queueio/queuespec.md
   - QueueVar: queueio/queuevar.md
-  - Django: queueio/django.md
+  - Django: queueio/django/README.md
   - Changelog: CHANGELOG.md

{queueio-0.6.0 → queueio-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "queueio"
-version = "0.6.0"
+version = "0.8.0"
 description = "Python background queues with an async twist"
 readme = "README.md"
 license = "MIT"
@@ -15,13 +15,14 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: System :: Distributed Computing",
 ]
-requires-python = ">=3.14"
+requires-python = ">=3.15"
 dependencies = [
     "dill>=0.3.9",
+    "noio>=0.3",
     "pika>=1.3.2",
     "textual>=3.2.0",
     "typer>=0.15.4",
@@ -29,6 +30,7 @@ dependencies = [
 
 [project.optional-dependencies]
 django = ["django>=6.0", "django-cmd>=3.0"]
+psycopg = ["psycopg>=3.3"]
 
 [project.entry-points.djp]
 queueio = "queueio.django.djp"
@@ -38,18 +40,20 @@ queueio = "queueio.__main__:app"
 
 [dependency-groups]
 dev = [
-    "basedpyright>=1.32.1",
+    "basedpyright>=1.40.2",
     "django-extensions",
     "djp",
     "queueio[django]",
+    "queueio[psycopg]",
     "mkdocs-material>=9.7.1",
     "mkdocs-same-dir>=0.1.3",
     "pytest>=8.4.1",
-    "pytest-cov>=6.0.0",
+    "pytest-cov>=7.0.0",
     "pytest-timeout>=2.4.0",
-    "ruff>=0.9.6",
+    "ruff>=0.17.0",
     "textual-dev>=1.7.0",
     "types-pika>=1.2.0b1",
+    "psycopg>=3.3.3",
 ]
 
 [tool.ruff.lint]
@@ -65,15 +69,19 @@ register = [
     "queueio.samples.priority",
     "queueio.samples.queuevar",
 ]
-pika = "amqp://localhost:5672"
+broker = "amqp://localhost:5672"
 
 [tool.pytest.ini_options]
+markers = ["no_global_qos: requires a broker without channel-wide QoS"]
+addopts = "-m 'not no_global_qos'"
 timeout = 30
 norecursedirs = ["site"]
 
 [tool.coverage.run]
 branch = true
 source = ["queueio"]
+patch = ["subprocess"]
+sigterm = true
 
 [build-system]
 requires = ["hatchling"]

queueio-0.8.0/pyrightconfig.json

@@ -0,0 +1,5 @@
+{
+  "pythonVersion": "3.15",
+  "typeCheckingMode": "standard",
+  "exclude": ["site", ".venv"]
+}

{queueio-0.6.0 → queueio-0.8.0}/queueio/__init__.py

@@ -2,7 +2,7 @@ from contextlib import contextmanager
 
 from .gather import gather as gather
 from .pause import pause as pause
-from .queueio import QueueIO as RealQueueIO
+from .queueio import QueueIO as QueueIO
 from .queueio import priority as priority
 from .queuevar import QueueVar as QueueVar
 from .registry import routine as routine
@@ -10,5 +10,5 @@ from .registry import routine as routine
 
 @contextmanager
 def activate():
-    with RealQueueIO().activate():
+    with QueueIO.default() as queueio, queueio.activate():
         yield

{queueio-0.6.0 → queueio-0.8.0}/queueio/__main__.py

@@ -1,14 +1,13 @@
-from contextlib import suppress
 from typing import Annotated
 
 import typer
 from typer import Argument
 from typer import Typer
 
-from .monitor import Monitor
 from .queueio import QueueIO
 from .queuespec import QueueSpec
 from .worker import Worker
+lazy from .monitor import Monitor
 
 app = Typer()
 
@@ -32,8 +31,7 @@ app.add_typer(
 @routine_app.command("list")
 def routine_list():
     """Show all registered routines."""
-    queueio = QueueIO()
-    try:
+    with QueueIO.default() as queueio:
         routines = queueio.routines()
 
         if not routines:
@@ -53,8 +51,6 @@ def routine_list():
         print(f"{'-' * name_width}-+-{'-' * path_width}")
         for routine, path in zip(routines, function_paths, strict=False):
             print(f"{routine.name:<{name_width}} | {path:<{path_width}}")
-    finally:
-        queueio.shutdown()
 
 
 @app.command(rich_help_panel="Commands")
@@ -64,17 +60,16 @@ def monitor(raw: bool = False):
     Show a live view of queueio activity. Use --raw for detailed event output.
     """
     if raw:
-        queueio = QueueIO()
-        events = queueio.subscribe({object})
-        try:
-            while True:
-                print(events.get())
-        except KeyboardInterrupt:
-            print("Shutting down gracefully.")
-        finally:
-            queueio.shutdown()
+        with QueueIO.default() as queueio:
+            events = queueio.subscribe({object})
+            try:
+                while True:
+                    print(events.get())
+            except KeyboardInterrupt:
+                print("Shutting down gracefully.")
     else:
-        Monitor().run()
+        with QueueIO.default() as queueio:
+            Monitor(queueio).run()
 
 
 @app.command(rich_help_panel="Commands")
@@ -94,8 +89,8 @@ def run(
     The worker will process invocations from the specified queue,
     as many at a time as specified by the concurrency.
     """
-    queueio = QueueIO()
-    Worker(queueio, queuespec)()
+    with QueueIO.default() as queueio:
+        Worker(queueio, queuespec)()
 
 
 @app.command(rich_help_panel="Commands")
@@ -103,14 +98,13 @@ def sync(
     recreate: Annotated[
         bool,
         typer.Option(
-            help="Delete and recreate queues that have incompatible arguments. "
-            "WARNING: This will lose any pending messages in those queues.",
+            help="Recreate all resources for the broker and journal. "
+            "WARNING: This will lose pending messages.",
         ),
     ] = False,
 ):
-    """Sync known queues to the broker."""
-    queueio = QueueIO()
-    try:
+    """Sync resources for the broker and journal."""
+    with QueueIO.default() as queueio:
         routines = queueio.routines()
 
         if not routines:
@@ -119,33 +113,21 @@ def sync(
 
         queues = sorted({routine.queue for routine in routines})
 
-        print(f"Syncing queues for {len(routines)} routine(s):")
-        if recreate:
-            for queue in queues:
-                print(f"  Recreating queue: {queue}")
-                with suppress(Exception):
-                    queueio.delete(queue=queue)
-
-        failed = []
+        print(f"Discovered queues for {len(routines)} routine(s):")
         for queue in queues:
-            print(f"  Ensuring queue exists: {queue}")
-            try:
-                queueio.create(queue=queue)
-            except Exception:
-                failed.append(queue)
+            print(f"  {queue}")
 
-        if failed:
+        try:
+            queueio.sync(queues, recreate=recreate)
+        except Exception:
             print(
-                f"\nError: {len(failed)} queue(s) have incompatible arguments: "
-                f"{', '.join(failed)}\n"
-                f"Re-run with --recreate to delete and recreate them.\n"
-                f"WARNING: This will lose any pending messages in those queues."
+                "\nError: Failed to sync resources.\n"
+                "Re-run with --recreate to recreate them.\n"
+                "WARNING: This will lose pending messages."
             )
-            raise typer.Exit(1)
+            raise typer.Exit(1) from None
 
         print(f"Successfully synced {len(queues)} queue(s)")
-    finally:
-        queueio.shutdown()
 
 
 @queue_app.command("purge")
@@ -164,8 +146,7 @@ def queue_purge(
     This will remove all pending messages from the given queues.
     Use with caution as this operation cannot be undone.
     """
-    queueio = QueueIO()
-    try:
+    with QueueIO.default() as queueio:
         queue_list = [q.strip() for q in queues.split(",") if q.strip()]
         if not queue_list:
             print("Error: No valid queue names provided")
@@ -176,8 +157,6 @@ def queue_purge(
             queueio.purge(queue=queue)
 
         print(f"Successfully purged {len(queue_list)} queue(s)")
-    finally:
-        queueio.shutdown()
 
 
 if __name__ == "__main__":

queueio-0.8.0/queueio/backend.py

@@ -0,0 +1,18 @@
+from abc import ABC
+from abc import abstractmethod
+from contextlib import AbstractContextManager
+
+from .broker import Broker
+from .journal import Journal
+
+
+class Backend(ABC):
+    """A backend provides context-managed access to a broker and journal."""
+
+    @abstractmethod
+    def broker(self) -> AbstractContextManager[Broker]:
+        raise NotImplementedError("Subclasses must implement this method.")
+
+    @abstractmethod
+    def journal(self) -> AbstractContextManager[Journal]:
+        raise NotImplementedError("Subclasses must implement this method.")

{queueio-0.6.0 → queueio-0.8.0}/queueio/broker.py

@@ -1,5 +1,6 @@
 from abc import ABC
 from abc import abstractmethod
+from collections.abc import Iterable
 
 from .queuespec import QueueSpec
 from .receiver import Receiver
@@ -13,10 +14,13 @@ class Broker(ABC):
     at-least-once delivery.
     """
 
-    @classmethod
     @abstractmethod
-    def from_uri(cls, uri: str, /):
-        """Create a broker instance from a URI."""
+    def sync(self, queues: Iterable[str], *, recreate: bool = False):
+        """Ensure the given queues are ready to use.
+
+        If recreate is True, destroy and recreate all resources,
+        losing any pending messages.
+        """
         raise NotImplementedError("Subclasses must implement this method.")
 
     @abstractmethod
@@ -24,16 +28,6 @@ class Broker(ABC):
         """Enqueue a message."""
         raise NotImplementedError("Subclasses must implement this method.")
 
-    @abstractmethod
-    def create(self, *, queue: str):
-        """Create a queue if it doesn't exist."""
-        raise NotImplementedError("Subclasses must implement this method.")
-
-    @abstractmethod
-    def delete(self, *, queue: str):
-        """Delete a queue."""
-        raise NotImplementedError("Subclasses must implement this method.")
-
     @abstractmethod
     def purge(self, *, queue: str):
         """Purge all messages from the queue."""