drasi-lib on drasi-lib for Python

Postgres dashboard

Mon, 01 Jan 0001 00:00:00 +0000

This builds a running dashboard over a Postgres table: rows appear when inserted, move when updated, and disappear when they stop matching — without polling and without writing any UI code. Everything comes from the published package and published plugins.

You need Docker and network access to ghcr.io.

The database

Start Postgres configured for logical replication:

docker run -d --name drasi-demo-pg \
 -e POSTGRES_PASSWORD=drasi -e POSTGRES_USER=drasi -e POSTGRES_DB=drasidemo \
 -p 5433:5432 postgres:16-alpine \
 postgres -c wal_level=logical -c max_replication_slots=8 -c max_wal_senders=8

Create the table, along with the publication the source replicates from and the replica identity that makes Postgres include the old row in updates and deletes:

Python sources

Mon, 01 Jan 0001 00:00:00 +0000

A Python source is one you feed yourself. Register it, then call push_change when your application changes something worth querying.

await drasi.add_python_source("orders")

Pushing a node

await drasi.push_change(
 "orders",
 {
 "op": "insert",
 "id": "o1",
 "labels": ["Order"],
 "properties": {"id": "o1", "status": "open", "total": 42},
 },
)

op is one of insert, update or delete. The aliases add and remove are accepted, and the value is case-insensitive, so INSERT works too.

id is the key, not a property

id identifies the node in the graph. A query selecting o.id reads a property called id, so emit it in properties as well or the column comes back None.

Python reactions

Mon, 01 Jan 0001 00:00:00 +0000

A reaction receives the diffs a continuous query produces. The simplest is a callable:

def on_results(event):
 for diff in event["results"]:
 if diff["type"] == "ADD":
 print("entered:", diff["data"])
 elif diff["type"] == "DELETE":
 print("left:", diff["data"])
 else:
 print("changed:", diff["before"], "->", diff["after"])


await drasi.add_python_reaction("watch", ["open-orders"], on_results)

One reaction can watch several queries. The event carries which query produced it, so a single handler can serve them all.

Async callbacks

An async callable works the same way, and is awaited on your event loop, so it can do async work of its own:

Streaming results

Mon, 01 Jan 0001 00:00:00 +0000

Anything you can receive through a callback can also be consumed as an async iterator, which usually reads better and lets you use ordinary control flow.

Query results

async for event in await drasi.query_results("open-orders"):
 for diff in event["results"]:
 print(diff["type"], diff.get("data"))

The stream ends when it is closed or the engine shuts down. Breaking out of the loop closes it.

Each stream is backed by its own reaction. Pass reaction_id to name it, which makes it visible to list_reactions and lets you remove it explicitly:

Query middleware

Mon, 01 Jan 0001 00:00:00 +0000

Middleware runs over a source’s changes before the query sees them, so a query can match on data that the source does not emit in the shape the query needs.

Declaring middleware and applying it are two steps. A declaration names an instance; a source’s pipeline decides where it runs. A declaration nothing refers to does nothing.

await drasi.add_query(
 "orders-by-city",
 "MATCH (o:Order) RETURN o.id AS id, o.city AS city",
 [{"id": "orders", "pipeline": ["flatten"]}],
 middleware=[
 {
 "name": "flatten",
 "kind": "promote",
 "config": {"mappings": [{"path": "$.address.city", "target_name": "city"}]},
 }
 ],
)

The source pushes {"address": {"city": "Cambridge"}}, and the query selects o.city. Without the pipeline that column is None, because city is nested rather than a property of the node. promote lifts it, and the query resolves it.

Plugins

Mon, 01 Jan 0001 00:00:00 +0000

Drasi’s sources, reactions, bootstrap providers, secret stores and identity providers are plugins: self-contained native libraries (.so, .dylib, .dll) that this host loads at runtime, exactly as drasi-server does. All five types can be loaded and selected from Python. That means a Python application can follow Postgres, Kafka or Kubernetes without anyone writing Python bindings for each one.

Installing one

resolved = await drasi.install_plugin("source/postgres")

That resolves the reference, picks the build matching this host, downloads it, loads it, and returns what it found. Short references are expanded against the default registry, so source/postgres means ghcr.io/drasi-project/source/postgres.

Error handling

Mon, 01 Jan 0001 00:00:00 +0000

Every failure raised by drasi-lib is a DrasiError or a subclass of one, and carries a stable code you can branch on.

from drasi import DrasiError

try:
 await drasi.add_query("open", "MATCH (o:Order", ["orders"])
except DrasiError as err:
 print(err.code, err)

The hierarchy

DrasiError
├── ConfigError
├── UnknownKindError
├── SourceError
├── StreamLaggedError
└── PluginError
 ├── PluginNotFoundError
 ├── PluginCompatibilityError
 └── PluginSignatureError

Catching DrasiError catches everything from the library and nothing from anywhere else, so it is safe to wrap a whole block. Catching a subclass narrows to one kind of problem — PluginSignatureError on its own, say, if an unverified plugin should be fatal but a missing one should not.

The blocking API

Mon, 01 Jan 0001 00:00:00 +0000

drasi.sync.Drasi mirrors the async API method for method, minus the await. It suits scripts, notebooks, test fixtures and existing synchronous code that has no event loop to hand.

import time

from drasi.sync import Drasi

OPEN_ORDERS = """
MATCH (o:Order)
WHERE o.status = 'open'
RETURN o.id AS id, o.total AS total
"""

with Drasi.create("script") as drasi:
 drasi.start()
 drasi.add_python_source("orders")
 drasi.add_query("open", OPEN_ORDERS, ["orders"])
 drasi.wait_for_query("open")

 drasi.push_change(
 "orders",
 {
 "op": "insert",
 "id": "o1",
 "labels": ["Order"],
 "properties": {"id": "o1", "status": "open", "total": 42},
 },
 )

 # A query processes changes asynchronously, so give it a moment before
 # reading the result set. `query_results` is the alternative: it yields each
 # change as it lands rather than making you guess how long to wait.
 time.sleep(1)
 print(drasi.get_query_results("open"))

Note with, not async with, and Drasi.create(...) returning the engine directly rather than an awaitable.

Typing

Mon, 01 Jan 0001 00:00:00 +0000

drasi-lib ships type information: the package is marked with py.typed, the native extension has a stub, and the shapes it accepts and returns are declared in drasi.types. Type checkers pick all of that up with no configuration.

from drasi import Drasi
from drasi.types import QueryResultEvent, SourceChange


def on_results(event: QueryResultEvent) -> None:
 for diff in event["results"]:
 print(diff["type"])


def order(order_id: str) -> SourceChange:
 return {
 "op": "insert",
 "id": order_id,
 "labels": ["Order"],
 "properties": {"id": order_id, "status": "open"},
 }

TypedDicts, not classes

The shapes are TypedDicts rather than dataclasses, so plain dicts keep working. The types describe what the API accepts; they do not change it. Nothing forces you to import them, and code written without annotations behaves identically.