pgque-py 0.2.0rc1__py3-none-any.whl

pgque/__init__.py

@@ -0,0 +1,44 @@
+# Copyright 2026 Nikolay Samokhvalov. Apache-2.0 license.
+# PgQue includes code derived from PgQ (ISC license,
+# Marko Kreen / Skype Technologies OU).
+
+"""pgque -- Python client for PgQue (PgQ Universal Edition).
+
+Quickstart::
+
+    import pgque
+
+    with pgque.connect("postgresql://localhost/mydb") as client:
+        client.send("orders", {"order_id": 42}, type="order.created")
+        client.conn.commit()
+
+See https://github.com/NikolayS/pgque for the SQL schema install and
+full documentation.
+"""
+
+from .client import PgqueClient, connect
+from .consumer import Consumer
+from .errors import (
+    PgqueBatchNotFound,
+    PgqueConnectionError,
+    PgqueConsumerNotFound,
+    PgqueError,
+    PgqueQueueNotFound,
+)
+from .types import Event, Message
+
+__version__ = "0.2.0rc1"
+
+__all__ = [
+    "PgqueClient",
+    "Consumer",
+    "Message",
+    "Event",
+    "PgqueError",
+    "PgqueConnectionError",
+    "PgqueQueueNotFound",
+    "PgqueBatchNotFound",
+    "PgqueConsumerNotFound",
+    "connect",
+    "__version__",
+]

pgque/client.py

@@ -0,0 +1,461 @@
+# Copyright 2026 Nikolay Samokhvalov. Apache-2.0 license.
+# PgQue includes code derived from PgQ (ISC license,
+# Marko Kreen / Skype Technologies OU).
+
+"""PgqueClient -- thin Python wrapper over the pgque SQL API."""
+
+import json
+from typing import Any, Optional, Union
+
+import psycopg
+
+from .errors import (
+    PgqueBatchNotFound,
+    PgqueConnectionError,
+    PgqueError,
+    PgqueQueueNotFound,
+)
+from .types import Event, Message
+
+
+def connect(dsn: str, *, autocommit: bool = False) -> "PgqueClient":
+    """Open a connection to PostgreSQL and return a ``PgqueClient``.
+
+    The returned client owns the connection and must be closed via
+    ``client.close()`` or used as a context manager.
+
+    Args:
+        dsn: libpq connection string (``postgresql://...``).
+        autocommit: If True, the connection runs in autocommit mode.
+            Useful for one-off scripts and consumers that prefer
+            implicit transactions per statement.
+
+    Raises:
+        PgqueConnectionError: Connection could not be established.
+    """
+    try:
+        conn = psycopg.connect(dsn, autocommit=autocommit)
+    except psycopg.OperationalError as e:
+        raise PgqueConnectionError(str(e)) from e
+    return PgqueClient(conn, _owns_conn=True)
+
+
+def _wrap_sql_error(e: Exception) -> PgqueError:
+    """Map a raw psycopg error to a pgque exception subclass."""
+    msg = str(e)
+    low = msg.lower()
+    if "queue not found" in low:
+        return PgqueQueueNotFound(msg)
+    if "batch not found" in low:
+        return PgqueBatchNotFound(msg)
+    return PgqueError(msg)
+
+
+class PgqueClient:
+    """Thin wrapper around pgque SQL functions.
+
+    By default, methods execute SQL against the wrapped connection
+    without managing transactions; the caller decides when to
+    ``commit()``/``rollback()``. If the connection is in autocommit
+    mode, each statement is its own transaction.
+
+    Use ``pgque.connect(dsn)`` to construct a client that owns its
+    connection. Pass an existing ``psycopg.Connection`` to share one
+    with application code.
+    """
+
+    def __init__(
+        self,
+        conn: psycopg.Connection,
+        *,
+        _owns_conn: bool = False,
+    ):
+        self.conn = conn
+        self._owns_conn = _owns_conn
+
+    # --- context manager / lifecycle ------------------------------------
+
+    def __enter__(self) -> "PgqueClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying connection if owned by this client.
+
+        If the client was constructed with an externally-managed
+        connection, ``close()`` is a no-op.
+        """
+        if self._owns_conn and not self.conn.closed:
+            self.conn.close()
+
+    # --- producer -------------------------------------------------------
+
+    def send(
+        self,
+        queue: str,
+        payload: Any = None,
+        *,
+        type: str = "default",
+    ) -> int:
+        """Send a single message to a queue.
+
+        Maps to ``pgque.send(queue, payload)`` or
+        ``pgque.send(queue, type, payload)``.
+
+        Args:
+            queue: Target queue name.
+            payload: Message payload. Accepted forms:
+
+                - ``dict`` / ``list`` — JSON-serialised automatically.
+                - ``str`` — must be **valid JSON text** (e.g.
+                  ``'"hello"'``, ``'{"k": 1}'``, ``'42'``, ``'null'``).
+                  The value is cast to ``jsonb`` by PostgreSQL. The
+                  Python literal ``"hello"`` has content ``hello``,
+                  which is not valid JSON; pass ``'"hello"'`` or
+                  ``json.dumps("hello")`` instead.
+                - ``None`` — stored as JSON ``null``.
+                - :class:`Event` — ``type`` and ``payload`` are unpacked.
+
+            type: Event type (default ``"default"``). Ignored if
+                ``payload`` is an ``Event`` (its own ``type`` wins).
+
+        Returns:
+            The event ID assigned by pgque.
+        """
+        if isinstance(payload, Event):
+            type = payload.type
+            payload = payload.payload
+
+        if isinstance(payload, (dict, list)):
+            payload = json.dumps(payload)
+        elif payload is None:
+            payload = "null"
+
+        try:
+            if type and type != "default":
+                row = self.conn.execute(
+                    "select pgque.send(%s, %s, %s::jsonb)",
+                    (queue, type, payload),
+                ).fetchone()
+            else:
+                row = self.conn.execute(
+                    "select pgque.send(%s, %s::jsonb)",
+                    (queue, payload),
+                ).fetchone()
+        except psycopg.Error as e:
+            raise _wrap_sql_error(e) from e
+
+        return row[0]
+
+    def send_batch(
+        self,
+        queue: str,
+        type: str,
+        payloads: list,
+    ) -> list[int]:
+        """Send multiple messages in one SQL call.
+
+        Maps to ``pgque.send_batch(queue, type, payloads[])`` and returns event
+        IDs in input order. The call is atomic inside the current transaction.
+
+        Payload encoding matches ``send``: ``dict``/``list`` values are JSON
+        encoded, ``str`` values must already be valid JSON text, and ``None`` is
+        stored as JSON ``null`` rather than SQL NULL.
+        """
+        json_payloads = [
+            json.dumps(p) if isinstance(p, (dict, list))
+            else ("null" if p is None else p)
+            for p in payloads
+        ]
+        try:
+            row = self.conn.execute(
+                "select pgque.send_batch(%s, %s, %s::jsonb[])",
+                (queue, type, json_payloads),
+            ).fetchone()
+        except psycopg.Error as e:
+            raise _wrap_sql_error(e) from e
+        return list(row[0])
+
+    # --- consumer -------------------------------------------------------
+
+    def receive(
+        self,
+        queue: str,
+        consumer: str,
+        max_messages: int = 100,
+    ) -> list[Message]:
+        """Receive a batch of messages from a queue.
+
+        Maps to ``pgque.receive(queue, consumer, max_messages)``, which
+        opens a batch via ``next_batch`` internally. The caller must
+        ``ack()`` the batch (with the ``batch_id`` from any returned
+        message) to advance the consumer past it. ``ack()`` finishes the
+        whole underlying PgQ batch, including rows beyond ``max_messages``;
+        direct callers should pass a value large enough for the queue's
+        possible batch size before acknowledging.
+
+        Args:
+            queue: Queue name.
+            consumer: Consumer name (must be registered on the queue).
+            max_messages: Maximum number of messages to return from the
+                current batch.
+
+        Returns:
+            List of ``Message`` objects, possibly empty if no batch is
+            currently available (e.g. the ticker has not run since the
+            last enqueue).
+        """
+        try:
+            rows = self.conn.execute(
+                "select * from pgque.receive(%s, %s, %s)",
+                (queue, consumer, max_messages),
+            ).fetchall()
+        except psycopg.Error as e:
+            raise _wrap_sql_error(e) from e
+
+        return [
+            Message(
+                msg_id=r[0],
+                batch_id=r[1],
+                type=r[2],
+                payload=r[3],
+                retry_count=r[4],
+                created_at=r[5],
+                extra1=r[6],
+                extra2=r[7],
+                extra3=r[8],
+                extra4=r[9],
+            )
+            for r in rows
+        ]
+
+    def ack(self, batch_id: int) -> int:
+        """Acknowledge (finish) a batch. Advances the consumer past it.
+
+        Args:
+            batch_id: Batch ID from any ``Message`` in the batch.
+
+        Returns:
+            Result returned by ``pgque.ack`` (1 on success).
+        """
+        try:
+            row = self.conn.execute(
+                "select pgque.ack(%s)", (batch_id,)
+            ).fetchone()
+        except psycopg.Error as e:
+            raise _wrap_sql_error(e) from e
+        return row[0]
+
+    def force_next_tick(self, queue: str) -> Optional[int]:
+        """Force the next ``pgque.ticker(queue)`` call to insert a tick.
+
+        Maps to ``pgque.force_next_tick(queue)``. The SQL function bumps the
+        queue's event sequence so the next ticker pass skips the normal
+        ``ticker_max_count`` / ``ticker_max_lag`` thresholds. It does **not**
+        insert the tick itself; call ``pgque.ticker`` afterwards (via raw SQL or
+        a scheduler).
+
+        Returns:
+            The current last tick ID, or ``None`` for a brand-new / skipped
+            queue, matching the SQL function.
+        """
+        try:
+            row = self.conn.execute(
+                "select pgque.force_next_tick(%s)", (queue,)
+            ).fetchone()
+        except psycopg.Error as e:
+            raise _wrap_sql_error(e) from e
+        return row[0]
+
+    def force_tick(self, queue: str) -> Optional[int]:
+        """Deprecated compatibility alias for ``force_next_tick``."""
+        return self.force_next_tick(queue)
+
+    # --- experimental cooperative consumers -----------------------------
+    #
+    # Function names, edge-case behavior, and signatures for these methods
+    # may change before the cooperative API is marked stable. See the
+    # client README ("Experimental: cooperative consumers") and
+    # ``docs/reference.md`` for context.
+
+    def subscribe_subconsumer(
+        self,
+        queue: str,
+        consumer: str,
+        subconsumer: str,
+    ) -> int:
+        """Register ``subconsumer`` under logical ``consumer`` for ``queue``.
+
+        Maps to ``pgque.subscribe_subconsumer(queue, consumer, subconsumer)``.
+        Returns ``1`` for a new registration and ``0`` if the row already
+        existed.
+        """
+        try:
+            row = self.conn.execute(
+                "select pgque.subscribe_subconsumer(%s, %s, %s)",
+                (queue, consumer, subconsumer),
+            ).fetchone()
+        except psycopg.Error as e:
+            raise _wrap_sql_error(e) from e
+        return row[0]
+
+    def unsubscribe_subconsumer(
+        self,
+        queue: str,
+        consumer: str,
+        subconsumer: str,
+        *,
+        batch_handling: int = 0,
+    ) -> int:
+        """Unregister one subconsumer.
+
+        Maps to ``pgque.unsubscribe_subconsumer(queue, consumer,
+        subconsumer, batch_handling)``. The default ``batch_handling=0``
+        raises if the subconsumer holds an active batch; pass ``1`` to
+        route active messages through the same retry/DLQ policy as
+        ``nack`` before the row is removed.
+        """
+        try:
+            row = self.conn.execute(
+                "select pgque.unsubscribe_subconsumer(%s, %s, %s, %s)",
+                (queue, consumer, subconsumer, batch_handling),
+            ).fetchone()
+        except psycopg.Error as e:
+            raise _wrap_sql_error(e) from e
+        return row[0]
+
+    def receive_coop(
+        self,
+        queue: str,
+        consumer: str,
+        subconsumer: str,
+        *,
+        max_messages: int = 100,
+        dead_interval: Optional[str] = None,
+    ) -> list[Message]:
+        """Receive a batch of messages for one cooperative subconsumer.
+
+        Maps to ``pgque.receive_coop(queue, consumer, subconsumer,
+        max_return, dead_interval)``. The function auto-registers the
+        ``coop_main`` and ``coop_member`` rows on first call, so callers
+        do not need to ``subscribe_subconsumer`` ahead of time unless
+        they want to convert an existing normal consumer.
+
+        Args:
+            queue: Queue name.
+            consumer: Logical consumer (the ``coop_main`` row).
+            subconsumer: Per-worker member name.
+            max_messages: Maximum rows to return from the current batch.
+                ``ack(batch_id)`` advances the cooperative cursor past
+                the entire underlying batch, so set this >= the queue's
+                worst-case batch size or consume the full batch before
+                acking.
+            dead_interval: Optional PostgreSQL interval syntax (e.g.
+                ``"5 minutes"``). When set, allows takeover of a stale
+                sibling's batch under a fresh ``batch_id``; the old
+                token is invalidated.
+
+        Returns:
+            Possibly-empty list of ``Message`` objects.
+        """
+        try:
+            rows = self.conn.execute(
+                "select * from pgque.receive_coop(%s, %s, %s, %s, %s::interval)",
+                (queue, consumer, subconsumer, max_messages, dead_interval),
+            ).fetchall()
+        except psycopg.Error as e:
+            raise _wrap_sql_error(e) from e
+
+        return [
+            Message(
+                msg_id=r[0],
+                batch_id=r[1],
+                type=r[2],
+                payload=r[3],
+                retry_count=r[4],
+                created_at=r[5],
+                extra1=r[6],
+                extra2=r[7],
+                extra3=r[8],
+                extra4=r[9],
+            )
+            for r in rows
+        ]
+
+    def touch_subconsumer(
+        self,
+        queue: str,
+        consumer: str,
+        subconsumer: str,
+    ) -> int:
+        """Refresh the heartbeat for a registered subconsumer row.
+
+        Maps to ``pgque.touch_subconsumer(queue, consumer, subconsumer)``.
+        Does not create a row if one does not already exist; returns the
+        number of rows touched (``1`` when the subconsumer is registered,
+        ``0`` otherwise).
+        """
+        try:
+            row = self.conn.execute(
+                "select pgque.touch_subconsumer(%s, %s, %s)",
+                (queue, consumer, subconsumer),
+            ).fetchone()
+        except psycopg.Error as e:
+            raise _wrap_sql_error(e) from e
+        return row[0]
+
+    def nack(
+        self,
+        batch_id: int,
+        msg: Message,
+        retry_after: Union[int, float] = 60,
+        reason: Optional[str] = None,
+    ) -> None:
+        """Negatively acknowledge a single message.
+
+        Routes the message to the retry queue with a ``retry_after``
+        delay. If the message's ``retry_count`` is at or above the
+        queue's ``queue_max_retries``, it is moved to the dead-letter
+        queue instead.
+
+        After nacking individual messages, the caller should still
+        ``ack()`` the batch to finish it.
+
+        Args:
+            batch_id: Batch ID.
+            msg: The ``Message`` to retry.
+            retry_after: Seconds before the message becomes available
+                again (default 60).
+            reason: Optional reason text (stored on the DLQ row when
+                max retries is exceeded).
+        """
+        try:
+            self.conn.execute(
+                "select pgque.nack("
+                "  %s,"
+                "  ROW(%s, %s, %s, %s, %s, %s, %s, %s, %s, %s)::pgque.message,"
+                "  %s::interval,"
+                "  %s"
+                ")",
+                (
+                    batch_id,
+                    msg.msg_id,
+                    msg.batch_id,
+                    msg.type,
+                    json.dumps(msg.payload)
+                    if isinstance(msg.payload, (dict, list))
+                    else msg.payload,
+                    msg.retry_count,
+                    msg.created_at,
+                    msg.extra1,
+                    msg.extra2,
+                    msg.extra3,
+                    msg.extra4,
+                    f"{retry_after} seconds",
+                    reason,
+                ),
+            )
+        except psycopg.Error as e:
+            raise _wrap_sql_error(e) from e

pgque/consumer.py

@@ -0,0 +1,333 @@
+# Copyright 2026 Nikolay Samokhvalov. Apache-2.0 license.
+# PgQue includes code derived from PgQ (ISC license,
+# Marko Kreen / Skype Technologies OU).
+
+"""Consumer -- event-driven message consumer with LISTEN/NOTIFY support."""
+
+import logging
+import select
+import signal
+import threading
+import time
+from typing import Callable, Literal, Optional
+
+import psycopg
+from psycopg import sql
+
+from .client import PgqueClient
+from .types import Message
+
+logger = logging.getLogger("pgque")
+
+# Maximum time the LISTEN wait blocks before re-checking the stop flag.
+# Bounds shutdown latency to roughly this many seconds.
+_WAIT_SLICE_SECONDS = 0.5
+# PostgreSQL int4 max; request the whole batch by default.
+_DEFAULT_MAX_MESSAGES = 2_147_483_647
+
+
+class Consumer:
+    """Synchronous polling consumer with LISTEN/NOTIFY wakeup.
+
+    Usage::
+
+        consumer = Consumer(
+            dsn="postgresql://localhost/mydb",
+            queue="orders",
+            name="order_processor",
+        )
+
+        @consumer.on("order.created")
+        def handle_order(msg: Message):
+            process_order(msg.payload)
+
+        consumer.start()  # blocks until SIGTERM/SIGINT
+
+    Handler return semantics:
+        - If the handler returns without exception, the message is
+          considered processed.
+        - If the handler raises an exception, the message is nacked
+          with the default retry_after.
+        - If no handler is registered for a message type (and no
+          default ``"*"`` handler exists), the message is nacked
+          (sent to retry_queue, or to the dead-letter queue once
+          ``queue_max_retries`` is exhausted). To ack unknown types
+          instead, pass ``unknown_handler_policy="ack"``.
+
+    After all messages in a batch have been dispatched, the batch is
+    acked automatically.
+    """
+
+    def __init__(
+        self,
+        dsn: str,
+        *,
+        queue: str,
+        name: str,
+        poll_interval: int = 30,
+        max_messages: int = _DEFAULT_MAX_MESSAGES,
+        retry_after: int = 60,
+        unknown_handler_policy: Literal["nack", "ack"] = "nack",
+        subconsumer: Optional[str] = None,
+        dead_interval: Optional[str] = None,
+    ):
+        self.dsn = dsn
+        self.queue = queue
+        self.name = name
+        self.poll_interval = poll_interval
+        self.max_messages = max_messages
+        self.retry_after = retry_after
+        if unknown_handler_policy not in ("nack", "ack"):
+            raise ValueError(
+                "unknown_handler_policy must be 'nack' or 'ack', "
+                f"got {unknown_handler_policy!r}"
+            )
+        self._unknown_handler_policy = unknown_handler_policy
+
+        # Experimental cooperative-consumers mode. When ``subconsumer`` is
+        # set, the poll loop calls ``client.receive_coop(...)`` instead of
+        # the normal ``receive(...)``. ``dead_interval`` is meaningless
+        # outside coop mode and signals a programming error if provided.
+        if dead_interval is not None and subconsumer is None:
+            raise ValueError(
+                "dead_interval is only valid in cooperative mode "
+                "(set subconsumer=...)"
+            )
+        self.subconsumer = subconsumer
+        self.dead_interval = dead_interval
+
+        self._handlers: dict[str, Callable] = {}
+        self._default_handler: Optional[Callable] = None
+        self._running = False
+        self._log = logging.getLogger(f"pgque.consumer.{name}")
+
+    def on(self, event_type: str):
+        """Decorator to register a handler for a given event type.
+
+        Args:
+            event_type: The ``pgque.message.type`` value to match.
+                Use ``"*"`` to register a default/catch-all handler.
+        """
+
+        def decorator(func: Callable):
+            if event_type == "*":
+                self._default_handler = func
+            else:
+                self._handlers[event_type] = func
+            return func
+
+        return decorator
+
+    def start(self) -> None:
+        """Run the consume loop (blocks until SIGTERM/SIGINT).
+
+        Opens its own connection, subscribes to LISTEN, and polls for
+        batches. Each batch is processed and acked in a single
+        transaction.
+        """
+        self._running = True
+
+        # Graceful shutdown on signals; only main-thread invocations can
+        # install signal handlers. When the consumer is run from a worker
+        # thread (tests, embedded use), skip registration -- callers stop
+        # via Consumer.stop().
+        in_main_thread = threading.current_thread() is threading.main_thread()
+        original_sigterm = None
+        original_sigint = None
+
+        def _stop(signum, frame):
+            logger.info("received signal %s, shutting down", signum)
+            self._running = False
+
+        if in_main_thread:
+            original_sigterm = signal.getsignal(signal.SIGTERM)
+            original_sigint = signal.getsignal(signal.SIGINT)
+            signal.signal(signal.SIGTERM, _stop)
+            signal.signal(signal.SIGINT, _stop)
+
+        try:
+            with psycopg.connect(self.dsn, autocommit=True) as conn:
+                # Subscribe for wakeup notifications
+                channel = f"pgque_{self.queue}"
+                conn.execute(sql.SQL("LISTEN {}").format(sql.Identifier(channel)))
+                logger.info(
+                    "consumer %s listening on %s (poll=%ds)",
+                    self.name,
+                    self.queue,
+                    self.poll_interval,
+                )
+
+                while self._running:
+                    self._poll_once(conn)
+
+                    if not self._running:
+                        break
+
+                    # Wait for NOTIFY or poll_interval timeout in short
+                    # bounded slices. psycopg's conn.notifies() can
+                    # block uninterruptibly for the full timeout, which
+                    # makes stop() slow and can miss prompt wakeups.
+                    # Polling the underlying socket with
+                    # select() lets us re-check _running every SLICE
+                    # seconds and drain any pending NOTIFY immediately.
+                    self._wait_for_notify_or_stop(conn)
+
+        finally:
+            if in_main_thread:
+                signal.signal(signal.SIGTERM, original_sigterm)
+                signal.signal(signal.SIGINT, original_sigint)
+
+        logger.info("consumer %s stopped", self.name)
+
+    def stop(self) -> None:
+        """Request graceful shutdown (safe to call from another thread)."""
+        self._running = False
+
+    def _wait_for_notify_or_stop(self, conn: psycopg.Connection) -> None:
+        """Wait up to ``poll_interval`` for a NOTIFY, in short slices.
+
+        Returns early on any of:
+          * a NOTIFY arrives (drained from the connection),
+          * ``stop()`` flips ``_running`` to False,
+          * ``poll_interval`` elapses cumulatively.
+
+        Each slice is at most ``_WAIT_SLICE_SECONDS`` so ``stop()`` is
+        observed within ~SLICE seconds of the call.
+        """
+        # Drain any NOTIFY already buffered in libpq from the prior
+        # _poll_once (e.g. delivered alongside query results). Without
+        # this, a buffered notify sits in libpq until the socket
+        # becomes readable for some other reason -- select() won't see
+        # it, and wakeup latency stretches out. Restores the implicit
+        # entry-drain semantics of the old conn.notifies(timeout=...).
+        drained = False
+        for _notify in conn.notifies(timeout=0):
+            drained = True
+        if drained:
+            return
+
+        deadline = time.monotonic() + self.poll_interval
+        fd = conn.fileno()
+        while self._running:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return
+            slice_timeout = min(_WAIT_SLICE_SECONDS, remaining)
+            # select() returns when the socket is readable (notify
+            # delivered by the server) or when slice_timeout expires.
+            # It is a thin wrapper around the OS poll, so it is cheap
+            # and interruptible.
+            r, _w, _x = select.select([fd], [], [], slice_timeout)
+            if not self._running:
+                return
+            if r:
+                # Drain pending notifications without blocking. A
+                # zero timeout makes notifies() return immediately
+                # after consuming whatever is buffered.
+                for _notify in conn.notifies(timeout=0):
+                    pass
+                return
+
+    def _poll_once(self, conn: psycopg.Connection) -> None:
+        """Receive one batch and dispatch messages.
+
+        If any per-message ``nack()`` raises, all remaining messages in
+        the batch are still dispatched (their handlers run), but the
+        batch is NOT acked at the end -- the receive transaction commits
+        without finishing the batch, so PgQ redelivers the whole batch
+        on the next poll. Without this guard, swallowing a nack failure
+        and then acking would advance past the batch and silently drop
+        the failed message.
+        """
+        # Use a transaction block for receive + ack
+        with conn.transaction():
+            client = PgqueClient(conn)
+            if self.subconsumer is not None:
+                msgs = client.receive_coop(
+                    self.queue,
+                    self.name,
+                    self.subconsumer,
+                    max_messages=self.max_messages,
+                    dead_interval=self.dead_interval,
+                )
+            else:
+                msgs = client.receive(
+                    self.queue, self.name, self.max_messages
+                )
+
+            if not msgs:
+                return
+
+            batch_id = msgs[0].batch_id
+            logger.debug(
+                "batch %d: %d message(s)", batch_id, len(msgs)
+            )
+
+            nack_failed = False
+
+            for msg in msgs:
+                handler = self._handlers.get(msg.type, self._default_handler)
+                if handler is None:
+                    if self._unknown_handler_policy == "ack":
+                        self._log.warning(
+                            "no handler for event type=%s ev_id=%s; acking",
+                            msg.type,
+                            msg.msg_id,
+                        )
+                        continue
+                    self._log.warning(
+                        "no handler for event type=%s ev_id=%s; nacking",
+                        msg.type,
+                        msg.msg_id,
+                    )
+                    try:
+                        client.nack(
+                            batch_id,
+                            msg,
+                            retry_after=self.retry_after,
+                            reason=f"no handler for type={msg.type}",
+                        )
+                    except Exception:
+                        nack_failed = True
+                        self._log.exception(
+                            "nack failed for unhandled msg_id=%d; "
+                            "skipping batch ack so PgQ redelivers",
+                            msg.msg_id,
+                        )
+                        continue
+                    continue
+
+                try:
+                    handler(msg)
+                except Exception:
+                    self._log.exception(
+                        "handler failed for msg_id=%d, nacking",
+                        msg.msg_id,
+                    )
+                    try:
+                        client.nack(
+                            batch_id, msg, retry_after=self.retry_after
+                        )
+                    except Exception:
+                        nack_failed = True
+                        self._log.exception(
+                            "nack failed for msg_id=%d; "
+                            "skipping batch ack so PgQ redelivers",
+                            msg.msg_id,
+                        )
+                        continue
+
+            if nack_failed:
+                # Do NOT ack -- redeliver on next poll.
+                return
+
+            # pgque.ack returns 1 on success, 0 if the batch was already
+            # finished or not found (stale/double ack, cross-consumer
+            # race). Mirror the TS+Go consumers and log warn on 0; do
+            # not treat it as an error.
+            if client.ack(batch_id) == 0:
+                logger.warning(
+                    "pgque: ack batch %d returned 0 -- stale or double ack "
+                    "(batch already finished or not found)",
+                    batch_id,
+                )

pgque/errors.py

@@ -0,0 +1,25 @@
+# Copyright 2026 Nikolay Samokhvalov. Apache-2.0 license.
+# PgQue includes code derived from PgQ (ISC license,
+# Marko Kreen / Skype Technologies OU).
+
+"""Exception hierarchy for pgque."""
+
+
+class PgqueError(Exception):
+    """Base class for all pgque-raised errors."""
+
+
+class PgqueConnectionError(PgqueError):
+    """Failed to connect to PostgreSQL or the connection was lost."""
+
+
+class PgqueQueueNotFound(PgqueError):
+    """Queue does not exist (raised by pgque SQL with a recognizable message)."""
+
+
+class PgqueBatchNotFound(PgqueError):
+    """Batch ID does not exist or was already finished."""
+
+
+class PgqueConsumerNotFound(PgqueError):
+    """Consumer is not registered on the queue."""

pgque/types.py

@@ -0,0 +1,49 @@
+# Copyright 2026 Nikolay Samokhvalov. Apache-2.0 license.
+# PgQue includes code derived from PgQ (ISC license,
+# Marko Kreen / Skype Technologies OU).
+
+"""Message and Event types for pgque."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Optional
+
+
+@dataclass
+class Message:
+    """A message received from a pgque queue.
+
+    Maps to the ``pgque.message`` composite type:
+        msg_id      -- ev_id
+        batch_id    -- batch containing this message
+        type        -- ev_type
+        payload     -- ev_data (jsonb auto-decoded by psycopg, otherwise text)
+        retry_count -- ev_retry (None for first delivery)
+        created_at  -- ev_time
+        extra1..4   -- ev_extra1..ev_extra4
+    """
+
+    msg_id: int
+    batch_id: int
+    type: str
+    payload: Any
+    retry_count: Optional[int]
+    created_at: datetime
+    extra1: Optional[str] = None
+    extra2: Optional[str] = None
+    extra3: Optional[str] = None
+    extra4: Optional[str] = None
+
+
+@dataclass
+class Event:
+    """An event being published to a queue. Convenience type for ``Client.send``.
+
+    For most code, passing ``payload`` and ``type`` directly to ``send`` is
+    simpler. ``Event`` is useful when constructing events programmatically
+    or when the payload + metadata travel together.
+    """
+
+    payload: Any
+    type: str = "default"
+    extra: dict[str, str] = field(default_factory=dict)

pgque_py-0.2.0rc1.dist-info/METADATA

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: pgque-py
+Version: 0.2.0rc1
+Summary: Python client for PgQue -- PgQ Universal Edition
+Author-email: Nikolay Samokhvalov <nik@postgres.ai>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/NikolayS/pgque
+Project-URL: Repository, https://github.com/NikolayS/pgque
+Project-URL: Issues, https://github.com/NikolayS/pgque/issues
+Project-URL: Documentation, https://github.com/NikolayS/pgque/blob/main/docs/reference.md
+Keywords: postgres,postgresql,queue,pgq,pgque,background-jobs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psycopg[binary]<4,>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# pgque-py
+
+Python client for [PgQue](https://github.com/NikolayS/pgque) — the PgQ-based
+universal PostgreSQL queue. Thin wrapper over `pgque-api` SQL functions:
+`send`, `receive`, `ack`, `nack`, `force_next_tick`, plus a polling
+`Consumer` with `LISTEN`/`NOTIFY` wakeup.
+
+## Install
+
+After the first Python client release:
+
+```bash
+pip install pgque-py
+```
+
+Requires Python 3.10+ and PostgreSQL 14+ with the PgQue schema installed
+(`\i pgque.sql` — no extension required).
+
+## Database permissions
+
+The connecting database role needs `pgque_reader` to consume (`receive`, `ack`, `nack`, `subscribe`, `unsubscribe`) and `pgque_writer` to produce (`send`, `send_batch`). The two are **siblings** — neither inherits the other. An app that both produces and consumes (the typical case for code using this client) must be granted **both** roles:
+
+```sql
+grant pgque_reader to your_app_user;
+grant pgque_writer to your_app_user;
+```
+
+See [`docs/reference.md` — Roles and grants](../../docs/reference.md#roles-and-grants) for the full role table.
+
+## Quickstart
+
+```python
+import pgque
+
+with pgque.connect("postgresql://localhost/mydb") as client:
+    # one-time setup (typically in a migration)
+    client.conn.execute("select pgque.subscribe('orders', 'order_worker')")
+    client.conn.commit()
+
+    # producer: commit once to publish both calls atomically
+    event_id = client.send("orders", {"order_id": 42}, type="order.created")
+    batch_ids = client.send_batch("orders", "order.created", [
+        {"order_id": 43},
+        {"order_id": 44},
+    ])
+    client.conn.commit()
+    print(event_id, batch_ids)
+
+# consumer (separate process / thread)
+consumer = pgque.Consumer(
+    dsn="postgresql://localhost/mydb",
+    queue="orders",
+    name="order_worker",
+)
+
+@consumer.on("order.created")
+def handle_order(msg: pgque.Message) -> None:
+    print(f"got {msg.type}: {msg.payload}")
+
+# Optional: catch-all handler for types with no specific handler.
+# Without it, messages with unhandled types are nacked by default
+# (sent to retry_queue, or to the dead-letter queue once
+# queue_max_retries is exhausted). Register a "*" handler to take
+# explicit control.
+@consumer.on("*")
+def handle_unknown(msg: pgque.Message) -> None:
+    print(f"unhandled type {msg.type!r}: {msg.payload}")
+
+consumer.start()  # blocks until SIGTERM / SIGINT
+```
+
+### Consumer options
+
+`Consumer(..., max_messages=...)` controls the per-`receive` limit.
+The default is PostgreSQL's `int` maximum, so the consumer requests
+the whole PgQ batch before acknowledging it. `ack()` finishes the
+entire underlying PgQ batch, including rows beyond `max_messages`;
+only lower this value when it is at least as large as the queue's
+worst-case batch size, otherwise rows past the limit are silently
+skipped by the batch ack.
+
+### Handling unknown event types
+
+By default the consumer **nacks** any message whose type has no
+registered handler and no `"*"` catch-all. The message is retried (or
+dead-lettered once `queue_max_retries` is exhausted) so unknown types
+are never silently dropped.
+
+To ack unknown types instead, pass `unknown_handler_policy="ack"`:
+
+```python
+consumer = pgque.Consumer(
+    dsn="postgresql://localhost/mydb",
+    queue="orders",
+    name="order_worker",
+    unknown_handler_policy="ack",  # log WARNING and ack; do not nack
+)
+```
+
+## Experimental: cooperative consumers
+
+> **Experimental in PgQue 0.2.** Function names, edge-case behavior, and
+> client API shape may change before this feature is marked stable. Do
+> not use this as the only processing path for critical workloads
+> without idempotent handlers and stale-worker takeover tests.
+
+Cooperative consumers let several worker processes share **one logical
+consumer**. Each batch is handed to exactly one subconsumer; the main
+row owns the group cursor, member rows own active batches. See
+[`docs/reference.md` — Cooperative consumers / subconsumers](../../docs/reference.md#cooperative-consumers--subconsumers)
+for the SQL surface.
+
+Two-worker example (each worker holds its own connection / process):
+
+```python
+import pgque
+
+# worker-1
+c1 = pgque.Consumer(
+    dsn="postgresql://localhost/mydb",
+    queue="orders",
+    name="order_worker",
+    subconsumer="worker-1",
+    dead_interval="5 minutes",  # optional: take over a stale sibling
+)
+
+@c1.on("order.created")
+def handle(msg):
+    process(msg)
+
+c1.start()  # in a second process: subconsumer="worker-2"
+```
+
+`Consumer(subconsumer=...)` switches the poll loop to
+`receive_coop` and auto-registers the `coop_main` + `coop_member` rows
+on the first call. `dead_interval` is only valid in cooperative mode;
+passing it without `subconsumer` raises `ValueError`.
+
+The low-level methods on `PgqueClient` are also available for direct
+use:
+
+```python
+client.subscribe_subconsumer("orders", "order_worker", "worker-1")
+msgs = client.receive_coop(
+    "orders", "order_worker", "worker-1",
+    max_messages=100, dead_interval="5 minutes",
+)
+client.ack(msgs[0].batch_id)
+client.touch_subconsumer("orders", "order_worker", "worker-1")
+client.unsubscribe_subconsumer(
+    "orders", "order_worker", "worker-1", batch_handling=1,
+)
+```
+
+`unsubscribe_subconsumer(..., batch_handling=0)` (the default) raises if
+the subconsumer holds an active batch; pass `batch_handling=1` to route
+active messages through retry/DLQ before removal.
+
+A runnable two-worker demo lives at
+[`bench/coop_demo.py`](bench/coop_demo.py); run it against any pgque
+database with `PGQUE_TEST_DSN` set.
+
+## Manual ticking
+
+For tests, demos, or manual operation without `pg_cron`, use
+`client.force_next_tick(queue)` to force the **next** `pgque.ticker()` call to
+materialize a tick. It does not insert the tick itself:
+
+```python
+client.force_next_tick("orders")
+client.conn.execute("select pgque.ticker()")
+client.conn.commit()
+```
+
+`client.force_tick(queue)` remains as a deprecated compatibility alias.
+
+## Transactions
+
+`send` → ticker → `receive` must each run in its own committed transaction (PgQue is snapshot-based). `pgque.connect(dsn)` is non-autocommit by default — commit between produce and consumer. The `Consumer` is autocommit + explicit `conn.transaction()` around `receive + dispatch + ack`.
+
+Don't wrap `send` and `receive` in one explicit tx; same for `maint_retry_events` + `ticker`. See [snapshot rule](https://github.com/NikolayS/pgque/blob/main/docs/pgq-concepts.md#snapshot-rule).
+
+
+## Tests
+
+Integration tests require a running PostgreSQL with the PgQue schema
+installed. Set `PGQUE_TEST_DSN` and run pytest:
+
+```bash
+PGQUE_TEST_DSN=postgresql://postgres:pgque_test@localhost/pgque_test \
+    pytest clients/python/tests
+```
+
+Without `PGQUE_TEST_DSN`, the tests skip.
+
+## Distribution
+
+The PyPI distribution is `pgque-py`; the import package is `pgque`:
+
+```python
+import pgque
+```
+
+See [RELEASE.md](RELEASE.md) for publishing steps.
+
+## More
+
+- Schema install, full reference, tutorial:
+  <https://github.com/NikolayS/pgque>
+- Per-function SQL reference:
+  <https://github.com/NikolayS/pgque/blob/main/docs/reference.md>
+- Issues: <https://github.com/NikolayS/pgque/issues>
+
+## License
+
+Apache-2.0. Copyright 2026 Nikolay Samokhvalov.

pgque_py-0.2.0rc1.dist-info/RECORD

@@ -0,0 +1,10 @@
+pgque/__init__.py,sha256=6Au5wTrYBL9r0S1hLjHbI4_51KtS5qcMkyhkNV5sGEU,1017
+pgque/client.py,sha256=mR5fpe-MCtzd79RgbnmRD6hUJYE7CFlGRBMZFMj8p2g,15720
+pgque/consumer.py,sha256=Gi6Ty7k7fusN6qXckd_CGZLHGm2M-0ido9WC9rE7x1c,12683
+pgque/errors.py,sha256=ORjo02BxygfR-VlpVnoEBxc8NYHWf59GO3DzNY6pzAY,697
+pgque/types.py,sha256=repuehmcjPXJjmTPXUNwPhcrLurJPr6wDnT0JRVZlp8,1430
+pgque_py-0.2.0rc1.dist-info/licenses/LICENSE,sha256=4O_EJRa1pubA2kMIOnlg4m1ZeYcS6p2zAHlgQLzAzGk,10771
+pgque_py-0.2.0rc1.dist-info/METADATA,sha256=Dy1RGs_I3TkYZ8L4U1_Dl9fvQ_iGOp1Yz9BINDtmYnk,8411
+pgque_py-0.2.0rc1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pgque_py-0.2.0rc1.dist-info/top_level.txt,sha256=ZvNzuJtA1VF1VoGEKutME5Ai2FSDjO8PEIe8RN3DlgQ,6
+pgque_py-0.2.0rc1.dist-info/RECORD,,

pgque_py-0.2.0rc1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pgque_py-0.2.0rc1.dist-info/licenses/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Nikolay Samokhvalov
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pgque_py-0.2.0rc1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pgque