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:
- A PostgreSQL database is running.
- 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.
- Handlers are to be implemented by developers. There are basic examples
included in the
notified/handlersmodule. - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.