queueio 0.7.0__tar.gz → 0.8.0__tar.gz

{queueio-0.7.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.7.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.7.0 → queueio-0.8.0}/.gitignore

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

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

@@ -8,6 +8,24 @@ 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
 --------------------
 
@@ -125,7 +143,8 @@ 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.7.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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: queueio
-Version: 0.7.0
+Version: 0.8.0
 Summary: Python background queues with an async twist
 Author-email: Ryan Hiebert <ryan@ryanhiebert.com>
 License-Expression: MIT
@@ -10,11 +10,12 @@ 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
@@ -86,6 +87,14 @@ to allow a project to be deployed in multiple environments.
 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:
 
 ```python

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

@@ -59,6 +59,14 @@ to allow a project to be deployed in multiple environments.
 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:
 
 ```python

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

@@ -1,6 +1,6 @@
 [project]
 name = "queueio"
-version = "0.7.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",
@@ -39,7 +40,7 @@ queueio = "queueio.__main__:app"
 
 [dependency-groups]
 dev = [
-    "basedpyright>=1.32.1",
+    "basedpyright>=1.40.2",
     "django-extensions",
     "djp",
     "queueio[django]",
@@ -47,9 +48,9 @@ dev = [
     "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",
@@ -71,12 +72,16 @@ register = [
 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.7.0 → queueio-0.8.0}/pyrightconfig.json

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

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

@@ -4,10 +4,10 @@ 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()
 

{queueio-0.7.0 → queueio-0.8.0}/queueio/broker_test.py

@@ -25,6 +25,7 @@ class TestMyBroker(BaseBrokerTest):
 """
 
 import threading
+import time
 from functools import wraps
 
 import pytest
@@ -47,6 +48,18 @@ def skip_if_unsupported(feature_attr):
     return decorator
 
 
+def wait_for(predicate, timeout=1.0, settle=0.05):
+    """Poll until predicate() is true, or until the timeout expires.
+
+    Then wait briefly, so that a receiver exceeding its limit has time to
+    deliver the excess message before the test asserts an exact count.
+    """
+    deadline = time.monotonic() + timeout
+    while not predicate() and time.monotonic() < deadline:
+        time.sleep(0.001)
+    time.sleep(settle)
+
+
 class BaseBrokerTest:
     """Base class with common tests for all broker implementations."""
 
@@ -80,7 +93,7 @@ class BaseBrokerTest:
         thread.start()
 
         # Wait for receiver to reach prefetch limit or timeout
-        thread.join(timeout=0.1)
+        wait_for(lambda: len(received_messages) >= prefetch_limit)
 
         # Should have received exactly prefetch_limit messages and be blocked
         assert len(received_messages) == prefetch_limit
@@ -113,13 +126,13 @@ class BaseBrokerTest:
         thread.start()
 
         # Wait for initial consumption up to prefetch limit
-        thread.join(timeout=0.1)
+        wait_for(lambda: len(received_messages) >= prefetch_limit)
         assert len(received_messages) == prefetch_limit
         assert thread.is_alive()  # Should be blocked
 
         # Pause first message - should free capacity for third message
         receiver.pause(received_messages[0])
-        thread.join(timeout=0.1)
+        wait_for(lambda: len(received_messages) >= 3)
         assert len(received_messages) == 3
 
         # Unpause first message - should receive capacity again
@@ -151,18 +164,18 @@ class BaseBrokerTest:
         thread.start()
 
         # Initial consumption up to prefetch limit
-        thread.join(timeout=0.1)
+        wait_for(lambda: len(received_messages) >= prefetch_limit)
         assert len(received_messages) == prefetch_limit
         assert thread.is_alive()  # Should be blocked
 
         # Finish first message - should allow consuming third message
         receiver.finish(received_messages[0])
-        thread.join(timeout=0.1)
+        wait_for(lambda: len(received_messages) >= 3)
         assert len(received_messages) == 3
 
         # Finish second message - should allow consuming fourth message
         receiver.finish(received_messages[1])
-        thread.join(timeout=0.1)
+        wait_for(lambda: len(received_messages) >= 4)
         assert len(received_messages) == 4
 
         broker.shutdown()
@@ -200,8 +213,7 @@ class BaseBrokerTest:
         thread2.start()
 
         # Allow both receivers to receive up to their limits
-        thread1.join(timeout=0.1)
-        thread2.join(timeout=0.1)
+        wait_for(lambda: len(receiver1_messages) + len(receiver2_messages) >= 5)
 
         # Both receivers should respect their prefetch limits and be blocked
         total_received = len(receiver1_messages) + len(receiver2_messages)

queueio-0.8.0/queueio/conftest.py

@@ -0,0 +1,98 @@
+import faulthandler
+import os
+import threading
+from contextlib import nullcontext
+from typing import TextIO
+
+import pytest
+from _pytest.capture import CaptureManager
+
+# Grace beyond the per-test timeout for pytest-timeout to fail the test.
+WATCHDOG_MARGIN = 15
+# Inactivity limit when per-test timeouts are disabled.
+WATCHDOG_DEFAULT = 60
+# How long the process may take to exit after pytest finishes.
+WATCHDOG_EXIT = 10
+
+_watchdog_file: TextIO | None = None
+_watchdog_limit: float = WATCHDOG_DEFAULT
+
+
+def _watchdog(seconds: float):
+    """Exit with all thread stacks if no progress is made within ``seconds``.
+
+    Each call resets the deadline. The timer runs in a C-level thread,
+    so it fires even if Python code is stuck.
+    """
+    if _watchdog_file is not None:
+        faulthandler.dump_traceback_later(seconds, exit=True, file=_watchdog_file)
+
+
+def pytest_configure(config: pytest.Config):
+    """Ensure the test suite always exits, even when nobody is watching.
+
+    pytest-timeout only covers individual tests. The watchdog also covers
+    collection and interpreter exit, and dumps every thread's stack before
+    exiting so that the hang can be diagnosed afterwards.
+    """
+    global _watchdog_file, _watchdog_limit
+
+    try:
+        timeout = float(config.getoption("timeout", None) or config.getini("timeout"))
+    except ValueError:
+        timeout = 0
+    _watchdog_limit = timeout + WATCHDOG_MARGIN if timeout > 0 else WATCHDOG_DEFAULT
+
+    # Write to the real stderr, not pytest's capture of it.
+    capman = config.pluginmanager.getplugin("capturemanager")
+    if isinstance(capman, CaptureManager):
+        suspended = capman.global_and_fixture_disabled()
+    else:
+        suspended = nullcontext()
+    with suspended:
+        _watchdog_file = os.fdopen(os.dup(2), "w")
+    _watchdog(_watchdog_limit)
+
+
+def pytest_collectstart():
+    _watchdog(_watchdog_limit)
+
+
+def pytest_collectreport():
+    _watchdog(_watchdog_limit)
+
+
+def pytest_runtest_logstart():
+    _watchdog(_watchdog_limit)
+
+
+def pytest_runtest_logreport():
+    _watchdog(_watchdog_limit)
+
+
+def pytest_sessionfinish():
+    _watchdog(_watchdog_limit)
+
+
+def pytest_unconfigure():
+    _watchdog(WATCHDOG_EXIT)
+
+
+@pytest.fixture(autouse=True)
+def check_thread_cleanup():
+    """Ensure that threads are not left running."""
+    initial_threads = set(threading.enumerate())
+    yield
+    final_threads = {t for t in threading.enumerate() if t.is_alive()}
+    new_threads = final_threads - initial_threads
+
+    if new_threads:
+        thread_info = []
+        for thread in new_threads:
+            daemon = "daemon" if thread.daemon else "non-daemon"
+            thread_info.append(f"  - {thread.name} ({daemon})")
+
+        pytest.fail(
+            f"Test left {len(new_threads)} thread(s) running:\n"
+            + "\n".join(thread_info)
+        )

{queueio-0.7.0 → queueio-0.8.0}/queueio/monitor.py

@@ -1,3 +1,4 @@
+from noio import ShutDown
 from textual.app import App
 from textual.app import ComposeResult
 from textual.widgets import DataTable
@@ -5,7 +6,6 @@ from textual.widgets import Footer
 from textual.widgets import Header
 
 from .invocation import Invocation
-from .queue import ShutDown
 from .queueio import QueueIO
 from .result import Err
 from .result import Ok

{queueio-0.7.0 → queueio-0.8.0}/queueio/pika/broker.py

@@ -19,6 +19,17 @@ class PikaBroker(Broker):
     @classmethod
     @contextmanager
     def connect(cls, connection: ThreadsafeConnection) -> Generator[PikaBroker]:
+        channel = connection.channel()
+        try:
+            if not channel.supports_global_qos():
+                raise RuntimeError(
+                    "Could not verify channel-wide QoS support. QueueIO requires "
+                    "it for concurrency limits and task suspension. "
+                    "On RabbitMQ, set deprecated_features.permit.global_qos = true in "
+                    "rabbitmq.conf and restart RabbitMQ."
+                )
+        finally:
+            channel.close()
         broker = cls(connection)
         try:
             yield broker

queueio-0.8.0/queueio/pika/broker_test.py

@@ -0,0 +1,38 @@
+import pytest
+
+from queueio.broker_test import BaseBrokerTest
+from queueio.queueio import QueueIO
+
+from . import PikaBackend
+
+
+def test_global_qos_supported():
+    with PikaBackend.connect(QueueIO.broker_uri()) as backend, backend.broker():
+        pass
+
+
+@pytest.mark.no_global_qos
+def test_global_qos_required():
+    with (
+        PikaBackend.connect(QueueIO.broker_uri()) as backend,
+        pytest.raises(RuntimeError) as caught,
+        backend.broker(),
+    ):
+        pytest.fail("Broker opened without channel-wide QoS support")
+
+    assert "Could not verify channel-wide QoS support" in str(caught.value)
+    assert "On RabbitMQ, set" in str(caught.value)
+    assert "deprecated_features.permit.global_qos = true" in str(caught.value)
+
+
+class TestPikaBroker(BaseBrokerTest):
+    supports_multiple_queues = True
+    supports_weighted_queue_subscriptions = False
+
+    @pytest.fixture
+    def broker(self):
+        with (
+            PikaBackend.connect(QueueIO.broker_uri()) as backend,
+            backend.broker() as broker,
+        ):
+            yield broker

{queueio-0.7.0 → queueio-0.8.0}/queueio/pika/journal_test.py

@@ -1,6 +1,7 @@
 import pytest
 
 from queueio.journal_test import BaseJournalTest
+from queueio.queueio import QueueIO
 
 from . import PikaBackend
 
@@ -9,7 +10,7 @@ class TestPikaJournal(BaseJournalTest):
     @pytest.fixture
     def journal(self):
         with (
-            PikaBackend.connect("amqp://localhost:5672") as backend,
+            PikaBackend.connect(QueueIO.broker_uri()) as backend,
             backend.journal() as journal,
         ):
             yield journal

{queueio-0.7.0 → queueio-0.8.0}/queueio/pika/threadsafe.py

@@ -5,6 +5,7 @@ from collections.abc import Mapping
 from concurrent.futures import Future
 from contextlib import contextmanager
 from contextlib import suppress
+from queue import Empty
 from queue import Queue
 from queue import ShutDown
 from threading import Event
@@ -33,7 +34,13 @@ class ThreadsafeConnection:
         )
         self.__thread = Thread(target=self.__connection.ioloop.start)
         self.__thread.start()
-        opened.result()
+        try:
+            opened.result()
+        except BaseException:
+            # Stop the ioloop so a failed connection doesn't leak its thread.
+            self.__connection.ioloop.stop()
+            self.__thread.join()
+            raise
 
     def __wait[T](self, fn: Callable[[], T]):
         # TODO: Throw connection exceptions on all waiters
@@ -95,6 +102,38 @@ class ThreadsafeChannel:
         finally:
             self.__pending.remove(future)
 
+    def supports_global_qos(self) -> bool:
+        """Probe global QoS on a fresh, disposable channel.
+
+        Global QoS shares a concurrency limit across a receiver's queues.
+        Updating that limit lets suspended tasks free capacity for other tasks.
+        """
+        queues = []
+        try:
+            self.qos(prefetch_count=1, global_qos=True)
+            for _ in range(2):
+                result = self.queue_declare("", exclusive=True, auto_delete=True)
+                queue = cast(str, result.method.queue)
+                queues.append(queue)
+                self.publish("", queue, b"")
+                self.consume(queue)
+            try:
+                self.__messages.get(timeout=5)
+                try:
+                    self.__messages.get(timeout=0.2)
+                except Empty:
+                    pass
+                else:
+                    return False
+                self.qos(prefetch_count=2, global_qos=True)
+                self.__messages.get(timeout=5)
+            except Empty:
+                return False
+            return True
+        finally:
+            for queue in queues:
+                self.delete(queue)
+
     def queue_declare(
         self,
         queue: str,

queueio-0.8.0/queueio/pika/threadsafe_test.py

@@ -0,0 +1,20 @@
+import socket
+
+import pytest
+from pika import ConnectionParameters
+from pika.exceptions import AMQPConnectionError
+
+from .threadsafe import ThreadsafeConnection
+
+
+def test_failed_connection_stops_ioloop_thread():
+    # Find a local port with nothing listening on it.
+    with socket.socket() as sock:
+        sock.bind(("127.0.0.1", 0))
+        port = sock.getsockname()[1]
+
+    # The autouse check_thread_cleanup fixture fails if the ioloop thread leaks.
+    with pytest.raises(AMQPConnectionError):
+        ThreadsafeConnection(
+            ConnectionParameters(host="127.0.0.1", port=port, connection_attempts=1)
+        )