dorm.contrib.listen_notify

PostgreSQL pub/sub via LISTEN / NOTIFY.

See LISTEN / NOTIFY for recipes.

API

dorm.contrib.listen_notify.listen(*channels: str, using: str = 'default') async

Async context manager that LISTENs on one or more channels.

Yields a :class:_ListenChannel that's also an async iterator — iterate it to receive :class:Notification instances. On exit the helper UNLISTENs and returns the dedicated connection back to the pool::

async with listen("orders") as ch:
    async for n in ch:
        process(n.payload)
        if some_condition:
            break

A dedicated connection is checked out for the lifetime of the block — LISTEN ties the subscription to a single backend, so the pool's connection-recycling logic must not swap it out from under the iterator.

dorm.contrib.listen_notify.notify(channel: str, payload: str = '', *, using: str = 'default') -> None

Synchronously publish a NOTIFY message.

The message is delivered when the surrounding transaction commits; if no transaction is active it is delivered immediately. Empty payloads are valid and useful as bare wake-up signals.

Implemented via the pg_notify(text, text) function rather than the NOTIFY statement so caller-supplied payloads pass through psycopg's parameter binding instead of being string-formatted.

dorm.contrib.listen_notify.anotify(channel: str, payload: str = '', *, using: str = 'default') -> None async

Async counterpart of :func:notify.

dorm.contrib.listen_notify.Notification dataclass

A single NOTIFY payload as observed by a LISTEN session.

channel matches the channel name the listener subscribed to. payload is whatever the publisher sent (PG ≥ 9.0 allows up to 8000 bytes; longer payloads must be sliced by the publisher). pid is the backend pid of the publishing session — useful for self-message filtering.