Skip to content

Events service

consortium.server.services.events_service

EventsService()

register_event_handler_to_event_type(event_type, event_handler)

Registers an async event handler for the specified event type.

Parameters:

Name Type Description Default
event_type EventType

The event type to subscribe the handler to.

 required
event_handler Callable[[Event], Coroutine[Any, Any, None]]

An async callable that accepts an Event and is invoked whenever the event type is triggered.

 required

Raises:

Type Description
InvalidEventTypeError

If the provided event type does not correspond to a valid EventType member.
EventHandlerAlreadyRegisteredError

If the same handler is already registered for the given event type.

deregister_event_handler_from_event_type(event_type, event_handler)

Removes a previously registered event handler from the specified event type.

Parameters:

Name Type Description Default
event_type EventType

The event type to unsubscribe the handler from.

 required
event_handler Callable[[Event], Coroutine[None, None, None]]

The async callable to remove.

 required

Raises:

Type Description
EventHandlerNotRegisteredError

If the handler is not currently registered for the given event type.

get_registered_event_handlers_from_event_type(event_type)

Returns all handlers currently registered for the specified event type.

Parameters:

Name Type Description Default
event_type EventType

The event type whose handlers to retrieve.

 required

Returns:

Type Description
list[Callable[[EventType], Coroutine[None, None, None]]]

A list of registered handlers. Empty if no handlers are registered for the
list[Callable[[EventType], Coroutine[None, None, None]]]

event type.

get_event_types_from_registered_event_handler(event_handler)

Returns all event types that the given handler is currently registered for.

Parameters:

Name Type Description Default
event_handler Callable[[Event], Coroutine[Any, Any, None]]

The handler to look up.

 required

Returns:

Type Description
list[EventType]

A list of event types the handler is subscribed to. Empty if the handler is
list[EventType]

not registered for any event type.

get_all_event_types()

Returns all supported event types.

Returns:

Type Description
list[str]

A list of all values from the EventType enum.

trigger_event(event_type, message='', data=None) async

Triggers an event, invoking all handlers registered for the given event type.

Handlers run concurrently. A handler that fails or is cancelled does not affect the others: every failure is collected and re-raised together as an ExceptionGroup once all handlers have finished. Event hooks that raise EventHookTriggerError (the framework-level signal from consortium.framework.signal_exceptions.event_hooks_signal_exceptions) from on_triggered() have that error remapped to the consortium-level EventHookTriggerError, preserving the original message and detail.

Because handlers run concurrently, and because separate triggers are dispatched as independent tasks, a handler may be entered again before an earlier call has returned. Handlers that mutate shared state across an await must guard it, and no ordering is guaranteed between handlers or between triggers.

Parameters:

Name Type Description Default
event_type EventType

The type of event to trigger.

 required
message str

A human-readable description of the event.

 ''
data JSON | None

Structured data payload associated with the event. Defaults to an empty dict when None.

 None

Raises:

Type Description
ExceptionGroup

If one or more handlers fail. May contain the consortium-level EventHookTriggerError (remapped from the framework-level signal raised by a handler's on_triggered()), asyncio.CancelledError for a handler that was cancelled, and any other exception a handler raised.
CancelledError

If the caller awaiting this method is itself cancelled, in which case the pending handlers are cancelled too.