queueio 0.6.0__tar.gz → 0.7.0__tar.gz

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

@@ -8,6 +8,25 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com).
 [Unreleased]
 ------------
 
+[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 +125,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.6.0...HEAD
+[Unreleased]: https://github.com/ryanhiebert/queueio/compare/tag/0.7.0...HEAD
+[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.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: queueio
-Version: 0.6.0
+Version: 0.7.0
 Summary: Python background queues with an async twist
 Author-email: Ryan Hiebert <ryan@ryanhiebert.com>
 License-Expression: MIT
@@ -21,6 +21,8 @@ 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 +73,17 @@ 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/'
 ```
 
 Sync the queues to the broker:

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

@@ -46,17 +46,17 @@ 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/'
 ```
 
 Sync the queues to the broker:

{queueio-0.6.0 → queueio-0.7.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.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "queueio"
-version = "0.6.0"
+version = "0.7.0"
 description = "Python background queues with an async twist"
 readme = "README.md"
 license = "MIT"
@@ -29,6 +29,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"
@@ -42,6 +43,7 @@ dev = [
     "django-extensions",
     "djp",
     "queueio[django]",
+    "queueio[psycopg]",
     "mkdocs-material>=9.7.1",
     "mkdocs-same-dir>=0.1.3",
     "pytest>=8.4.1",
@@ -50,6 +52,7 @@ dev = [
     "ruff>=0.9.6",
     "textual-dev>=1.7.0",
     "types-pika>=1.2.0b1",
+    "psycopg>=3.3.3",
 ]
 
 [tool.ruff.lint]
@@ -65,7 +68,7 @@ register = [
     "queueio.samples.priority",
     "queueio.samples.queuevar",
 ]
-pika = "amqp://localhost:5672"
+broker = "amqp://localhost:5672"
 
 [tool.pytest.ini_options]
 timeout = 30

queueio-0.7.0/pyrightconfig.json

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

{queueio-0.6.0 → queueio-0.7.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.7.0}/queueio/__main__.py

@@ -1,4 +1,3 @@
-from contextlib import suppress
 from typing import Annotated
 
 import 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.7.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.7.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."""

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

@@ -60,7 +60,7 @@ class BaseBrokerTest:
     @pytest.mark.timeout(2)
     def test_prefetch_limits_message_consumption(self, broker):
         """Verify that prefetch parameter limits message consumption."""
-        broker.create(queue="test-queue")
+        broker.sync(["test-queue"])
         broker.purge(queue="test-queue")
 
         # Enqueue more messages than prefetch limit
@@ -93,7 +93,7 @@ class BaseBrokerTest:
     @pytest.mark.timeout(2)
     def test_suspend_resume_affects_prefetch_capacity(self, broker):
         """Verify suspending messages frees capacity and resuming reduces it."""
-        broker.create(queue="test-queue")
+        broker.sync(["test-queue"])
         broker.purge(queue="test-queue")
 
         # Enqueue messages
@@ -131,7 +131,7 @@ class BaseBrokerTest:
     @pytest.mark.timeout(2)
     def test_complete_message_frees_prefetch_capacity(self, broker):
         """Verify completing messages frees up capacity."""
-        broker.create(queue="test-queue")
+        broker.sync(["test-queue"])
         broker.purge(queue="test-queue")
 
         # Enqueue more messages than prefetch limit
@@ -171,7 +171,7 @@ class BaseBrokerTest:
     @pytest.mark.timeout(2)
     def test_multiple_receivers_independent_prefetch_limits(self, broker):
         """Verify multiple receivers operate with independent prefetch limits."""
-        broker.create(queue="test-queue")
+        broker.sync(["test-queue"])
         broker.purge(queue="test-queue")
 
         # Enqueue enough messages for both receivers
@@ -223,8 +223,7 @@ class BaseBrokerTest:
     @skip_if_unsupported("supports_multiple_queues")
     def test_receive_supports_multiple_queues(self, broker):
         """Verify broker can receive from multiple queues."""
-        broker.create(queue="queue1")
-        broker.create(queue="queue2")
+        broker.sync(["queue1", "queue2"])
         broker.purge(queue="queue1")
         broker.purge(queue="queue2")
 
@@ -260,10 +259,7 @@ class BaseBrokerTest:
     def test_multiple_queues_with_mixed_empty_and_filled(self, broker):
         """Verify broker handles multiple queues with some empty, some with messages."""
 
-        broker.create(queue="empty1")
-        broker.create(queue="filled")
-        broker.create(queue="empty2")
-        broker.create(queue="also_filled")
+        broker.sync(["empty1", "filled", "empty2", "also_filled"])
         broker.purge(queue="empty1")
         broker.purge(queue="filled")
         broker.purge(queue="empty2")
@@ -308,8 +304,7 @@ class BaseBrokerTest:
         probability in the round-robin selection.
         """
 
-        broker.create(queue="priority_queue")
-        broker.create(queue="normal_queue")
+        broker.sync(["priority_queue", "normal_queue"])
         broker.purge(queue="priority_queue")
         broker.purge(queue="normal_queue")
 
@@ -410,9 +405,7 @@ class BaseBrokerTest:
         the message, not just cycle by a fixed amount.
         """
 
-        broker.create(queue="empty")
-        broker.create(queue="queue1")
-        broker.create(queue="queue2")
+        broker.sync(["empty", "queue1", "queue2"])
         broker.purge(queue="empty")
         broker.purge(queue="queue1")
         broker.purge(queue="queue2")
@@ -473,7 +466,7 @@ class BaseBrokerTest:
     @pytest.mark.timeout(2)
     def test_higher_priority_consumed_first(self, broker):
         """Verify that higher priority messages are consumed before lower ones."""
-        broker.create(queue="test-queue")
+        broker.sync(["test-queue"])
         broker.purge(queue="test-queue")
 
         # Enqueue low priority first, then high priority

{queueio-0.6.0 → queueio-0.7.0}/queueio/freethreading_test.py

@@ -22,7 +22,11 @@ def test_all_queueio_modules_preserve_freethreading():
     for _, modname, _ in pkgutil.walk_packages(
         queueio.__path__, f"{queueio.__name__}."
     ):
-        if not modname.endswith("_test") and ".django" not in modname:
+        if (
+            not modname.endswith("_test")
+            and ".django" not in modname
+            and ".psycopg" not in modname
+        ):
             importlib.import_module(modname)
 
     assert sys._is_gil_enabled() is False

{queueio-0.6.0 → queueio-0.7.0}/queueio/journal.py

@@ -4,12 +4,6 @@ from collections.abc import Iterator
 
 
 class Journal(ABC):
-    @classmethod
-    @abstractmethod
-    def from_uri(cls, uri: str, /):
-        """Create a journal instance from a URI."""
-        raise NotImplementedError("Subclasses must implement this method.")
-
     @abstractmethod
     def subscribe(self) -> Iterator[bytes]:
         raise NotImplementedError("Subclasses must implement this method.")

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

@@ -17,9 +17,9 @@ class Monitor(App):
 
     TITLE = "queueio Monitor"
 
-    def __init__(self):
+    def __init__(self, queueio: QueueIO):
         super().__init__()
-        self.__queueio = QueueIO()
+        self.__queueio = queueio
         self.__thread = Thread(target=self.__listen)
         self.__events = self.__queueio.subscribe(
             {

queueio-0.7.0/queueio/pika/__init__.py

@@ -0,0 +1,31 @@
+from collections.abc import Generator
+from contextlib import AbstractContextManager
+from contextlib import contextmanager
+
+from pika import URLParameters
+
+from queueio.backend import Backend
+
+from .broker import PikaBroker
+from .journal import PikaJournal
+from .threadsafe import ThreadsafeConnection
+
+
+class PikaBackend(Backend):
+    def __init__(self, connection: ThreadsafeConnection):
+        self.__connection = connection
+
+    @classmethod
+    @contextmanager
+    def connect(cls, uri: str, /) -> Generator[PikaBackend]:
+        connection = ThreadsafeConnection(URLParameters(uri))
+        try:
+            yield cls(connection)
+        finally:
+            connection.close()
+
+    def broker(self) -> AbstractContextManager[PikaBroker]:
+        return PikaBroker.connect(self.__connection)
+
+    def journal(self) -> AbstractContextManager[PikaJournal]:
+        return PikaJournal.connect(self.__connection)

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

@@ -1,7 +1,9 @@
+from collections.abc import Generator
+from collections.abc import Iterable
+from contextlib import contextmanager
+from contextlib import suppress
 from threading import Lock
 
-from pika import URLParameters
-from pika.connection import Parameters
 from pika.spec import BasicProperties
 
 from queueio.broker import Broker
@@ -15,17 +17,34 @@ class PikaBroker(Broker):
     """A broker enables producing and consuming messages on a queue."""
 
     @classmethod
-    def from_uri(cls, uri: str, /):
-        """Create a broker instance from a URI."""
-        return cls(URLParameters(uri))
+    @contextmanager
+    def connect(cls, connection: ThreadsafeConnection) -> Generator[PikaBroker]:
+        broker = cls(connection)
+        try:
+            yield broker
+        finally:
+            broker.shutdown()
 
-    def __init__(self, connection_params: Parameters):
-        self.__connection = ThreadsafeConnection(connection_params)
+    def __init__(self, connection: ThreadsafeConnection):
+        self.__connection = connection
         self.__channel = self.__connection.channel()
         self.__shutdown_lock = Lock()
         self.__shutdown = False
         self.__receivers = set[PikaReceiver]()
 
+    def sync(self, queues: Iterable[str], *, recreate: bool = False):
+        channel = self.__connection.channel()
+        try:
+            for queue in queues:
+                if recreate:
+                    with suppress(Exception):
+                        channel.delete(queue=queue)
+                channel.queue_declare(
+                    queue=queue, durable=True, arguments={"x-max-priority": 9}
+                )
+        finally:
+            channel.close()
+
     def enqueue(self, body: bytes, /, *, queue: str, priority: int):
         self.__channel.publish(
             exchange="",
@@ -34,18 +53,6 @@ class PikaBroker(Broker):
             properties=BasicProperties(priority=priority),
         )
 
-    def create(self, *, queue: str):
-        channel = self.__connection.channel()
-        channel.queue_declare(
-            queue=queue, durable=True, arguments={"x-max-priority": 9}
-        )
-        channel.close()
-
-    def delete(self, *, queue: str):
-        channel = self.__connection.channel()
-        channel.delete(queue=queue)
-        channel.close()
-
     def purge(self, *, queue: str):
         self.__channel.purge(queue=queue)
 
@@ -62,7 +69,4 @@ class PikaBroker(Broker):
             self.__shutdown = True
             for receiver in self.__receivers:
                 receiver.shutdown()
-            self.__connection.close()
-
-    def __del__(self):
-        self.shutdown()
+            self.__channel.close()

queueio-0.7.0/queueio/pika/broker_test.py

@@ -0,0 +1,18 @@
+import pytest
+
+from queueio.broker_test import BaseBrokerTest
+
+from . import PikaBackend
+
+
+class TestPikaBroker(BaseBrokerTest):
+    supports_multiple_queues = True
+    supports_weighted_queue_subscriptions = False
+
+    @pytest.fixture
+    def broker(self):
+        with (
+            PikaBackend.connect("amqp://localhost:5672") as backend,
+            backend.broker() as broker,
+        ):
+            yield broker

{queueio-0.6.0 → queueio-0.7.0}/queueio/pika/journal.py

@@ -1,10 +1,9 @@
+from collections.abc import Generator
 from collections.abc import Iterator
+from contextlib import contextmanager
 from threading import Lock
 from typing import cast
 
-from pika import URLParameters
-from pika.connection import Parameters
-
 from queueio.journal import Journal
 
 from .threadsafe import ThreadsafeConnection
@@ -12,14 +11,17 @@ from .threadsafe import ThreadsafeConnection
 
 class PikaJournal(Journal):
     @classmethod
-    def from_uri(cls, uri: str, /):
-        """Create a journal instance from a URI."""
-        return cls(URLParameters(uri))
-
-    def __init__(self, connection_params: Parameters):
-        self.__connection = ThreadsafeConnection(connection_params)
-        self.__subscribe_channel = self.__connection.channel()
-        self.__publish_channel = self.__connection.channel()
+    @contextmanager
+    def connect(cls, connection: ThreadsafeConnection) -> Generator[PikaJournal]:
+        journal = cls(connection)
+        try:
+            yield journal
+        finally:
+            journal.shutdown()
+
+    def __init__(self, connection: ThreadsafeConnection):
+        self.__subscribe_channel = connection.channel()
+        self.__publish_channel = connection.channel()
 
         declare_result = self.__subscribe_channel.queue_declare("", exclusive=True)
         self.__subscribe_queue = cast(str, declare_result.method.queue)
@@ -55,4 +57,3 @@ class PikaJournal(Journal):
             self.__subscribe_channel.cancel(self.__subscribe_consumer_tag)
             self.__subscribe_channel.close()
             self.__publish_channel.close()
-            self.__connection.close()