iddqueue 0.13.0rc2__tar.gz → 0.13.0rc3__tar.gz

{iddqueue-0.13.0rc2 → iddqueue-0.13.0rc3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iddqueue
-Version: 0.13.0rc2
+Version: 0.13.0rc3
 Summary: Postgres Broker for Dramatiq Task Queue
 Keywords: postgres,task queue,dramatiq
 Author: Étienne BERSAC
@@ -27,8 +27,8 @@ A PostgreSQL broker and Results backend for [Dramatiq](https://dramatiq.io/),
 built on synchronous Psycopg 3. Tasks, results and coordination live in PostgreSQL;
 no Redis or ORM is required by IDDQueue.
 
-**Current release: [0.13.0rc2](https://pypi.org/project/iddqueue/0.13.0rc2/)** —
-a release candidate for evaluation. [GitHub assets](https://github.com/wa-pis/iddqueue/releases/tag/v0.13.0rc2)
+**Current release: [0.13.0rc3](https://pypi.org/project/iddqueue/0.13.0rc3/)** —
+a release candidate for evaluation. [GitHub assets](https://github.com/wa-pis/iddqueue/releases/tag/v0.13.0rc3)
 include the wheel, sdist and SHA256 checksums.
 
 IDDQueue is a fork of [DALIBO's dramatiq-pg](https://gitlab.com/dalibo/dramatiq-pg)
@@ -56,7 +56,7 @@ See [compatibility and API stability](SUPPORT.md).
 
 ```sh
 uv venv
-uv pip install "iddqueue[binary]==0.13.0rc2"
+uv pip install "iddqueue[binary]==0.13.0rc3"
 ```
 
 The `binary` extra supplies libpq. Base installs require system libpq;
@@ -119,11 +119,13 @@ Close broker-owned pools on shutdown; callers close pools they supply.
 
 ## Guides and examples
 
+[Domain actors and one worker bootstrap](docs/domains.md) are included since RC3.
+
 - [Documentation index](docs/index.md), [user guide](docs/user-guide.md), [API](docs/api.md).
 - [Detailed recipes](docs/recipes.md): transactions, middleware, controls, metrics and schedules.
 - [FastAPI](docs/fastapi.md): lifespan, async endpoint thread offload and separate worker.
 - [Deployment and retention](docs/deployment-guide.md), [why PostgreSQL](docs/why.md).
-- [RC notes](docs/rc-0.13.0rc2.md), [changelog](CHANGELOG.md), [release checks](docs/release.md).
+- [RC notes](docs/rc-0.13.0rc3.md), [changelog](CHANGELOG.md), [release checks](docs/release.md).
 
 The broker and result APIs are synchronous. Async actors use Dramatiq's AsyncIO
 middleware; FastAPI async endpoints offload publication to a thread.
@@ -138,12 +140,13 @@ is unverified. No tested Django integration is currently provided.
 ## Compared with dramatiq-pg
 
 Baseline: [dramatiq-pg 0.12.0](https://pypi.org/project/dramatiq-pg/0.12.0/),
-compared with the published IDDQueue 0.13.0rc2 prerelease. This describes the published version, not every
+compared with the published IDDQueue 0.13.0rc3 prerelease. This describes the published version, not every
 future upstream revision. Both projects provide a PostgreSQL Dramatiq broker.
 
-| Area | dramatiq-pg 0.12.0 | IDDQueue 0.13.0rc2 / practical benefit |
+| Area | dramatiq-pg 0.12.0 | IDDQueue 0.13.0rc3 / practical benefit |
 | --- | --- | --- |
 | Core storage and delivery | JSONB tasks/results, delayed tasks, LISTEN/NOTIFY, advisory locks, recovery and maintenance CLI | Preserved; at-least-once delivery still requires idempotent actors |
+| Actor initialization | Broker configured before actor imports | Opt-in Domain declarations import before DSN; explicit startup registration and domain queues |
 | Runtime | Python >=3.6,<4; Dramatiq >=1.5,<2; Psycopg 2 | Python >=3.10,<4; Dramatiq >=2.2.1,<3; synchronous Psycopg 3 and psycopg-pool |
 | Pool lifecycle | Psycopg 2 pools | Lazy owned pools, explicit close, caller-owned pool support |
 | Transactional publication | Regular enqueue | Caller-owned transaction API: commit business data and tasks together |
@@ -158,7 +161,7 @@ future upstream revision. Both projects provide a PostgreSQL Dramatiq broker.
 
 See [migration from dramatiq-pg](docs/migration.md) for dependency, pool,
 import, CLI and database changes, including backup and rollback. No throughput
-advantage is claimed here. The 0.13.0rc2 prerelease is available on PyPI; the legacy Django
+advantage is claimed here. The 0.13.0rc3 prerelease is available on PyPI; the legacy Django
 integration is archived and has not been verified with IDDQueue.
 
 ## Development and support

{iddqueue-0.13.0rc2 → iddqueue-0.13.0rc3}/README.md

@@ -6,8 +6,8 @@ A PostgreSQL broker and Results backend for [Dramatiq](https://dramatiq.io/),
 built on synchronous Psycopg 3. Tasks, results and coordination live in PostgreSQL;
 no Redis or ORM is required by IDDQueue.
 
-**Current release: [0.13.0rc2](https://pypi.org/project/iddqueue/0.13.0rc2/)** —
-a release candidate for evaluation. [GitHub assets](https://github.com/wa-pis/iddqueue/releases/tag/v0.13.0rc2)
+**Current release: [0.13.0rc3](https://pypi.org/project/iddqueue/0.13.0rc3/)** —
+a release candidate for evaluation. [GitHub assets](https://github.com/wa-pis/iddqueue/releases/tag/v0.13.0rc3)
 include the wheel, sdist and SHA256 checksums.
 
 IDDQueue is a fork of [DALIBO's dramatiq-pg](https://gitlab.com/dalibo/dramatiq-pg)
@@ -35,7 +35,7 @@ See [compatibility and API stability](SUPPORT.md).
 
 ```sh
 uv venv
-uv pip install "iddqueue[binary]==0.13.0rc2"
+uv pip install "iddqueue[binary]==0.13.0rc3"
 ```
 
 The `binary` extra supplies libpq. Base installs require system libpq;
@@ -98,11 +98,13 @@ Close broker-owned pools on shutdown; callers close pools they supply.
 
 ## Guides and examples
 
+[Domain actors and one worker bootstrap](docs/domains.md) are included since RC3.
+
 - [Documentation index](docs/index.md), [user guide](docs/user-guide.md), [API](docs/api.md).
 - [Detailed recipes](docs/recipes.md): transactions, middleware, controls, metrics and schedules.
 - [FastAPI](docs/fastapi.md): lifespan, async endpoint thread offload and separate worker.
 - [Deployment and retention](docs/deployment-guide.md), [why PostgreSQL](docs/why.md).
-- [RC notes](docs/rc-0.13.0rc2.md), [changelog](CHANGELOG.md), [release checks](docs/release.md).
+- [RC notes](docs/rc-0.13.0rc3.md), [changelog](CHANGELOG.md), [release checks](docs/release.md).
 
 The broker and result APIs are synchronous. Async actors use Dramatiq's AsyncIO
 middleware; FastAPI async endpoints offload publication to a thread.
@@ -117,12 +119,13 @@ is unverified. No tested Django integration is currently provided.
 ## Compared with dramatiq-pg
 
 Baseline: [dramatiq-pg 0.12.0](https://pypi.org/project/dramatiq-pg/0.12.0/),
-compared with the published IDDQueue 0.13.0rc2 prerelease. This describes the published version, not every
+compared with the published IDDQueue 0.13.0rc3 prerelease. This describes the published version, not every
 future upstream revision. Both projects provide a PostgreSQL Dramatiq broker.
 
-| Area | dramatiq-pg 0.12.0 | IDDQueue 0.13.0rc2 / practical benefit |
+| Area | dramatiq-pg 0.12.0 | IDDQueue 0.13.0rc3 / practical benefit |
 | --- | --- | --- |
 | Core storage and delivery | JSONB tasks/results, delayed tasks, LISTEN/NOTIFY, advisory locks, recovery and maintenance CLI | Preserved; at-least-once delivery still requires idempotent actors |
+| Actor initialization | Broker configured before actor imports | Opt-in Domain declarations import before DSN; explicit startup registration and domain queues |
 | Runtime | Python >=3.6,<4; Dramatiq >=1.5,<2; Psycopg 2 | Python >=3.10,<4; Dramatiq >=2.2.1,<3; synchronous Psycopg 3 and psycopg-pool |
 | Pool lifecycle | Psycopg 2 pools | Lazy owned pools, explicit close, caller-owned pool support |
 | Transactional publication | Regular enqueue | Caller-owned transaction API: commit business data and tasks together |
@@ -137,7 +140,7 @@ future upstream revision. Both projects provide a PostgreSQL Dramatiq broker.
 
 See [migration from dramatiq-pg](docs/migration.md) for dependency, pool,
 import, CLI and database changes, including backup and rollback. No throughput
-advantage is claimed here. The 0.13.0rc2 prerelease is available on PyPI; the legacy Django
+advantage is claimed here. The 0.13.0rc3 prerelease is available on PyPI; the legacy Django
 integration is archived and has not been verified with IDDQueue.
 
 ## Development and support

{iddqueue-0.13.0rc2 → iddqueue-0.13.0rc3}/iddqueue/__init__.py

@@ -1,10 +1,12 @@
 from .broker import PostgresBroker
 from .cancellation import ResultCancelled
+from .domains import Domain
 from .rate_limits import PostgresRateLimiterBackend
 from .results import PostgresBackend
 from .schema import generate_coordination_sql, generate_init_sql, generate_upgrade_sql
 
 __all__ = [
+    "Domain",
     "ResultCancelled",
     "PostgresBackend",
     "PostgresBroker",

iddqueue-0.13.0rc3/iddqueue/domains.py

@@ -0,0 +1,70 @@
+"""Framework-independent declarations, bound explicitly before worker startup."""
+
+import re
+
+from dramatiq import Actor
+from dramatiq.broker import Broker
+
+
+class _DeclarationBroker(Broker):
+    def __init__(self):
+        super().__init__(middleware=[])
+
+    def declare_queue(self, queue_name):
+        # Declarations create no transport resources.
+        pass
+
+    def enqueue(self, message, *, delay=None):
+        raise RuntimeError("Register the actor's Domain with a broker before sending")
+
+
+class Domain:
+    """One queue and qualified actor names; register once per process."""
+
+    def __init__(self, name):
+        if not isinstance(name, str) or not re.fullmatch(r"[a-zA-Z_][a-zA-Z0-9._-]*", name):
+            raise ValueError("domain name must be a valid Dramatiq queue name")
+        self.name = name
+        self._declarations = _DeclarationBroker()
+        self._broker = None
+        self._failed = False
+
+    def actor(self, fn=None, *, actor_name=None, priority=0, **options):
+        def decorate(fn):
+            if self._broker is not None or self._failed:
+                raise RuntimeError("Declare all domain actors before registration")
+            if "broker" in options or "queue_name" in options:
+                raise ValueError("Domain owns the broker and queue_name")
+            name = actor_name if actor_name is not None else fn.__name__
+            if not isinstance(name, str) or not name:
+                raise ValueError("actor_name must be a nonempty string")
+            return Actor(fn, broker=self._declarations, actor_name=f"{self.name}.{name}",
+                         queue_name=self.name, priority=priority, options=dict(options))
+        return decorate if fn is None else decorate(fn)
+
+    def register(self, broker):
+        if self._failed:
+            raise RuntimeError("Registration failed; create a new Domain and broker")
+        if not isinstance(broker, Broker):
+            raise TypeError("register requires a Dramatiq Broker")
+        if broker is self._broker:
+            return
+        if self._broker is not None:
+            raise RuntimeError("Domain is already registered with another broker")
+        actors = list(self._declarations.actors.values())
+        for actor in actors:
+            invalid = set(actor.options) - broker.actor_options
+            if invalid:
+                raise ValueError(f"Undefined actor options for {actor.actor_name}: {sorted(invalid)}")
+            if actor.actor_name in broker.actors:
+                raise ValueError(f"Actor {actor.actor_name!r} is already registered")
+        try:
+            for actor in actors:
+                actor.broker = broker
+                broker.declare_actor(actor)
+        except Exception:
+            for actor in actors:
+                actor.broker = self._declarations
+            self._failed = True
+            raise
+        self._broker = broker

{iddqueue-0.13.0rc2 → iddqueue-0.13.0rc3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "iddqueue"
-version = "0.13.0rc2"
+version = "0.13.0rc3"
 description = "Postgres Broker for Dramatiq Task Queue"
 authors = [{name = "Étienne BERSAC"}]
 license = "PostgreSQL"