larzbus

An in-process pub/sub event bus. Pure Python, zero dependencies.

Decouple your app: publishers announce that something happened, subscribers react, and neither knows about the other — with three things ad-hoc callback lists lack.

from larzbus import EventBus

bus = EventBus()

@bus.on("user.*")
def audit(event):
    print(event.topic, event.data)

bus.publish("user.created", {"id": 42})     # audit sees "user.created"

What makes it different

• Wildcard topics. Subscribe to user.* (one segment) or order.** (all remaining) and get every matching event — with the concrete topic on event.topic.
• Async delivery when you want it. bus.publish(topic, data, async_=True) runs handlers on a background thread, so one slow subscriber never blocks the publisher.
• Dead-letter path. A handler that raises doesn't take down the publish — the other handlers still run, and the event + exception go to your on_error handlers and a dead_letters log.
• Zero dependencies, thread-safe.

Install

pip install larzbus

Usage

from larzbus import EventBus

bus = EventBus()

# subscribe (decorator or direct); wildcards allowed
@bus.on("order.*")
def on_order(event):
    ...

sub = bus.subscribe("payment.completed", handler)
bus.once("startup", run_once)          # auto-unsubscribes after first delivery
sub.unsubscribe()

# publish
results = bus.publish("order.created", {"id": 1})   # list of handler returns
bus.publish("email.queued", payload, async_=True)    # non-blocking

# dead-letter
@bus.on_error
def failed(topic, event, exc):
    log.warning("handler failed on %s: %s", topic, exc)

bus.dead_letters      # [(topic, event, exception), ...]

Wildcards

pattern	matches
user.created	exactly that topic
user.*	user.created, user.deleted (one more segment)
order.**	order.created, order.item.added, … (any depth)

Tests

python -m unittest discover -s tests -v   # 17 tests, zero deps

The Larz stack

Pure-Python, zero-dependency building blocks: larz · larzchain · larzmoney · larzcrypt · larzdb · larzagent · larzchart · larzmark · larztask · larzvault · larzvm · larzcache · larzvalidate · larzid · larzrpc · larzstate · larzhttp · larzconf · larzcron · larzlimit · larzlog · larzcli · larzretry · larztime · larzpdf · larzpack · larztemplate · larzcolor · larztable · larzjson · larzbus

License

MIT © larz-scripter