Skip to main content

Notified

Notified is highly opinionated python library that provides a pub/sub-like functionality. It is designed to handle event notifications using PostgreSQL notify/listen events system.

Installation

pip install notified

Setup

Currently, for the service to work, the following setup is expected:

  1. A PostgreSQL database is running.
  2. Events table exists in the database and contains event id and name information. The id field is used to fetch event data, name is needed to determine which handlers to call.
  3. Handlers are to be implemented by developers. There are basic examples included in the notified/handlers module.
  4. To avoid sending big amounts of data over the channel, it is required to store event in a table and only include id of the record as event payload.

Usage

Server is the "manager" component: it listens for events and dispatches them to handlers. Each handler is executed in a separate thread. The following conde snipped shows how to run the server:

import typing as t

from notified.server import Server
from notified.handlers import HandlerResult, HandlerStatus


def my_handler(event_data: dict[str, t.Any]) -> HandlerResult:
    return HandlerResult(status=HandlerStatus.SUCCESS, payload=event_data)


connection_string = "postgresql://username:password@localhost:5432/database"
listen_channel = "events"

server = Server(listen_channel, connection_string)
server.register_handler("my_event", my_handler)
server.listen()

Client is the "publisher" component: it sends events to the server. The following code snippet shows how to send an event:

from notified.client import NotifyClient


connection_string = "postgresql://username:password@localhost:5432/database"
listen_channel = "events"

event_id = 42  # assuming that there's an event record in a table with id 42

client = NotifyClient(listen_channel, connection_string)
client.notify(str(event_id))

Alternatively, instead of explicitly defining client, the DB-level triggers can be used to send events every time new event is added to the table. The following is code snippet shows how to create a trigger, assuming that table with events is named events:

CREATE or REPLACE FUNCTION notify_event()
    RETURNS TRIGGER
    LANGUAGE 'plpgsql'
AS $BODY$
declare
begin
    if (TG_OP = 'INSERT') then
        PERFORM pg_notify('events', NEW.id::text);
    end if;
    return null;
end
$BODY$;
    
CREATE OR REPLACE TRIGGER notify_event
    AFTER INSERT
    ON events
    FOR EACH ROW
    EXECUTE PROCEDURE notify_event();

The "subscriber" (or "consumer") part of the workflow is expected to be implemented by developers using the library.

Configuration

There are following configuration options:

  • Events table name (default: events, environment variable: NOTIFIED_EVENTS_TABLE_NAME)
  • ID field name in the events table (default: id, environment variable: NOTIFIED_ID_FIELD_NAME)
  • Events channel polling timeout (default: 5 second, environment variable: NOTIFIED_CHANNEL_SELECT_TIMEOUT)

Each value can be configured either explicitly via code or via environment variable. For explicit configuration, see the following example:

from notified.config import NotifiedConfig
from notified.server import Server

config = NotifiedConfig(
    events_table="my_events", 
    id_field="pk",
    channel_select_timeout=10
)


server = Server(
    "events_channel",
    "postgresql://username:password@localhost:5432/database",
    conf=config
)
server.listen()

License

This project is licensed under the Apache License.

Metadata

Release files for notified 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for notified 0.1.0
File Size Uploaded Provenance Actions
notified-0.1.0.tar.gz 8.9 kB Without provenance Details for notified-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for notified 0.1.0
File Interpreter ABI Platform Actions
notified-0.1.0-py3-none-any.whl Python 3 none any Details for notified-0.1.0-py3-none-any.whl

Total release size: 19.7 kB

Release files / notified-0.1.0.tar.gz

Download URL notified-0.1.0.tar.gz
Size 8.9 kB
Tags Source
SHA-256 checksum
How to use checksums
6cd9d58d34fc23c4bfcab99de382248932f6641e8a319ba5dfa5b8a6e4448f75
BLAKE2b-256 checksum
How to use checksums
f832ef5153fb312575c4ba935f160f1729ba73eb46f3053704a9d6410ed30bd3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.4 CPython/3.12.8 Linux/6.8.0-1017-azure

Release files / notified-0.1.0-py3-none-any.whl

Download URL notified-0.1.0-py3-none-any.whl
Size 10.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5cf3c79c1773483c9f93f2792cc3fab8689acbfca4688d9d98327ad0bae0038a
BLAKE2b-256 checksum
How to use checksums
5750bcc761baa2f7b029ea34fee01e8ef98b34c4095c240021b4b23d800caed2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.4 CPython/3.12.8 Linux/6.8.0-1017-azure

Security for notified 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page