Abstract Event Manager API¶
This module defines event manager class API.
The main class of the module is the BaseEventManager
.
Event managers are expected to implement the interface as specified by
BaseEventManager
. A concrete implementation is present in the
event_manager
module.
-
class
encore.events.abstract_event_manager.
BaseEventManager
¶ This abstract class defines the API for Event Managers.
-
connect
(cls, func, filter=None, priority=0)¶ Add a listener for the event.
Parameters: - cls (class) – The class of events for which the listener is registered.
- func (callable) – A callable to be called when the event is emitted. The function should expect one argument which is the event instance which was emitted.
- filter (dict) –
Filters to match for before calling the listener. The listener is called only when the event matches all of the filter .
- Filter specification:
- key: string which is extended (. separated) name of an
- attribute of the event instance.
- value: the value of the specified attribute.
If the attribute does not exist then the filter is considered failed and the listener is not called.
- priority (int) – The priority of the listener. Higher priority listeners are called before lower priority listeners.
Note
The filtering is added so that future optimizations can be done on specific events with large number of handlers. For example there should be a fast way to filter key events to specific listeners rather than iterating through all listeners.
-
disable
(cls)¶ Disable the event from generating notifications.
Parameters: cls (class) – The class of events which we want to disable.
-
disconnect
(cls, func)¶ Disconnects a listener from being notified about the event’
Parameters: - cls (class) – The class of events for which the listener is registered.
- func (callable) – The callable which was registered for that class.
Raises: KeyError - if func is not already connected.
-
emit
(event, block=True)¶ Notifies all listeners about the event with the specified arguments.
Parameters: - event (instance of
BaseEvent
) – TheBaseEvent
instance to emit. - block (bool) – Whether to block the call until the event handling is finished.
If block is False, the event will be emitted in a separate thread
and the thread will be returned, so you can later query its status
or do
wait()
on the thread.
Note
Listeners of superclasses of the event are also called. Eg. a
BaseEvent
listener will also be notified about any derived class events.- event (instance of
-
enable
(cls)¶ Enable the event again to generate notifications.
Parameters: cls (class) – The class of events which we want to enable.
-
is_enabled
(cls)¶ Check if the event is enabled.
Parameters: cls (class) – The class of events which we want check the status of.
-
Events¶
The module also provides the base class for all event objects.
-
class
encore.events.abstract_event_manager.
BaseEvent
(source=None, **kwargs)¶ Base class for all events.
Parameters: -
mark_as_handled
()¶ Mark the event as handled so subsequent listeners are not notified.
-
post_emit
()¶ Called after emitting an event.
Can be used any event specific functionality, post event validation etc.
-
pre_emit
()¶ Called before emitting an event.
Can be used any event specific functionality, validation etc.
-