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[source]

This abstract class defines the API for Event Managers.

abstract connect(cls, func, filter=None, priority=0)[source]

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.

abstract disable(cls)[source]

Disable the event from generating notifications.

Parameters:

cls (class) – The class of events which we want to disable.

abstract disconnect(cls, func)[source]

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.

abstract emit(event, block=True)[source]

Notifies all listeners about the event with the specified arguments.

Parameters:

  • event (instance of BaseEvent) – The BaseEvent 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.

abstract enable(cls)[source]

Enable the event again to generate notifications.

Parameters:

cls (class) – The class of events which we want to enable.

abstract is_enabled(cls)[source]

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)[source]

Base class for all events.

Parameters:

  • source (object) – The object which generated the Event.

  • kwargs (dict) – Additional Event attributes which will be added to the Event object.

mark_as_handled()[source]

Mark the event as handled so subsequent listeners are not notified.

post_emit()[source]

Called after emitting an event.

Can be used any event specific functionality, post event validation etc.

pre_emit()[source]

Called before emitting an event.

Can be used any event specific functionality, validation etc.