Event System

The async pub/sub event system for graph mutation notifications.

EventBus

EventBus

Async pub/sub event bus for graph mutation events.

Thread-safety: This class is designed for single-threaded async use within one asyncio event loop. All operations are synchronous except handler invocation (which uses create_task).

Attributes:

Name	Type	Description
handler_timeout		Seconds before a slow handler triggers a warning.

subscriber_count property

subscriber_count: int

Number of currently registered handlers.

emit_count property

emit_count: int

Total number of events emitted since creation.

subscribe

subscribe(handler: EventHandler, *, event_types: set[GraphEventType] | None = None, label: str | None = None) -> None

Register an async callback to receive events.

Parameters:

Name	Type	Description	Default
handler	EventHandler	Async function that takes a GraphEvent.	required
event_types	set[GraphEventType] | None	Set of event types to filter on. None = receive all events.	None
label	str | None	Optional human-readable label for logging. Defaults to the function name.	None

unsubscribe

unsubscribe(handler: EventHandler) -> None

Remove a previously registered handler.

If the handler is not registered, this is a no-op.

Parameters:

Name	Type	Description	Default
handler	EventHandler	The same function object passed to subscribe().	required

emit

emit(event: GraphEvent) -> None

Fire an event to all matching subscribers.

Each handler is invoked in its own asyncio.Task — non-blocking. The emit call returns immediately.

Parameters:

Name	Type	Description	Default
event	GraphEvent	The graph event to broadcast.	required

Event Types

GraphEventType

Bases: str, Enum

GraphEvent

GraphEvent dataclass