Event reference#

EventListener#

class asyncio_event_hub.controller.EventListener(fnc: Callable[[T], Any], predicate: Callable[[T], bool] | None = None)#

New in version 1.0.

Represents a listener (handler) of an event.

fnc#

The actual registered handler function.

Type:: Callable[[T], Any]

predicate#

Condition function that gets called before fnc and must return True, if the fnc is to be called.

Type:: Optional[Callable[[T], bool]]

EventController#

class asyncio_event_hub.controller.EventController#

New in version 1.0.

Responsible for controlling the event loop, listening and emitting events.

property running: bool#: New in version 1.0.

Returns bool indicating if the controller is running or not.

property subcontrollers: List[EventController]#: New in version 1.0.

Returns a list of controller’s sub-controllers.

critical()#

New in version 1.0.

Method that returns an async context manager, that prevents any events from being processed while in the critical section.

Example:

async with controller.critical():
    # Can't process events here
    await something.initialize()

# Can process events here

start()#: New in version 1.0.

Starts the event loop of this master controller and it’s subcontrollers.

add_subcontroller(controller: EventController)#

New in version 1.0.

Adds a sub-controller, that also receives events emitted to the current controller. If this master controller is running and the controller being added is not, it is automatically started. If this master controller is not running, the controller being added is started, after this master controller is started.

Parameters:: controller (EventController) – The controller to add as a sub-controller.

remove_subcontroller(controller: EventController)#

New in version 1.0.

Removes the sub-controller. The sub-controller IS NOT stopped.

Parameters:: controller (EventController) – The controller to remove.
Raises:: ValueError – The controller is not a subcontroller of the current controller

stop()#

New in version 1.0.

Stops event loop asynchronously

Returns:: A Future object that can be used to await for the controller’s task to stop and also the tasks of all the subcontrollers.
Return type:: asyncio.Future

add_listener(event: Enum | str | int, fnc: Callable[[T], Any], predicate: Callable[[T], bool] | None = None)#

New in version 1.0.

Registers the function fnc as an event listener for event.

Parameters:

event (Union[Enum, str, int]) – The event of listener to add.
fnc (Callable) – The function listener to add.
predicate (Optional[Callable[[Any], bool]]) – Optional function parameter that accepts the same parameters as fnc and must return True, indicating if fnc is to be called or not. If it returns False, the fnc does not get called after event is emitted.

remove_listener(event: Enum | str | int, fnc: Callable)#

New in version 1.0.

Remove the function fnc from the list of listeners for event.

Parameters:

event (Union[Enum, str, int]) – The event of listener to remove.
fnc (Callable) – The function listener to remove.

Raises:

KeyError – The event doesn’t have any listeners.
ValueError – Provided function is not a listener.

listen(event: Enum | str | int)#

New in version 1.0.

Decorator used to register the function as an event listener.

Example:

ctrl = EventController()

@ctrl.listen("my_event")
async def event_handler():
    print("Received event")

Parameters:: event (Union[Enum, str, int]) – The event that needs to occur for the function to be called.

emit(event: Enum | str | int, *args, priority: int = 0, **kwargs) → Future#

New in version 1.0.

Emits an event by calling all the registered listeners from the event loop.

Example:

ctrl = EventController()
... # Add listeners (handlers)
ctrl.emit("my_event")

Parameters:

event (Union[Enum, str, int]) – The event to emit.
args – Variadic positional arguments passed to event listeners.
priority (int) –

New in version 1.1.

The priority of event. Events with higher priority are processed before the ones with lower priority. Defaults to 0. This is a keyword only priority.
kwargs – Variadic keyword arguments passed to event listeners.

Returns:

A future object that can be awaited. You can use this to wait for the event to actually be processed. The result of the future will always be None.

Return type:

asyncio.Future

Raises:

TypeError – Arguments provided don’t match all the listener parameters.

clear_queue()#: New in version 1.0.

Clears all emitted events from queue (recreates the queue).

async event_loop()#: New in version 1.0.

Event loop task.