Event API

Events are classes implementing the AbstractEvent interface

The EventHandler class is for creating objects with events. These events can occur once only during the life of an EventHandler or can occur several times. Check the event dispatching tutorial for an overview.

Abstract Event

class pulsar.async.events.AbstractEvent[source]

Abstract event handler

bind(callback)[source]

Bind a callback to this event.

remove_callback(callback)[source]

Remove a callback from the list

fired()[source]

The number of times this event has fired

fire(arg, **kwargs)[source]

Fire this event.

Event

class pulsar.async.events.Event(loop=None, name=None)[source]

The default implementation of AbstractEvent.

One time

class pulsar.async.events.OneTime(*, loop=None, name=None)[source]

An AbstractEvent which can be fired once only.

This event handler is a subclass of Future. Implemented mainly for the one time events of the EventHandler.

bind(callback)[source]

Bind a callback to this event.

fire(arg, exc=None, **kwargs)[source]

The callback handlers registered via the :meth:~AbstractEvent.bind` method are executed first.

Parameters:
  • arg – the argument
  • exc – optional exception

Events Handler

class pulsar.async.events.EventHandler(loop=None, one_time_events=None, many_times_events=None)[source]

A Mixin for handling events on async objects.

It handles OneTime events and Event that occur several times.

ONE_TIME_EVENTS = ()

Event names which occur once only.

MANY_TIMES_EVENTS = ()

Event names which occur several times.

events

The dictionary of all events.

event(name)[source]

Returns the Event at name.

If no event is registered for name returns nothing.

bind_event(name, callback)[source]

Register a callback with event.

The callback must be a callable accepting one positional parameter and at least the exc optional parameter:

def callback(arg, ext=None):
    ...

o.bind_event('start', callback)

the instance firing the event or the first positional argument passed to the fire_event() method.

Parameters:
  • name – the event name. If the event is not available a warning message is logged.
  • callback – a callable receiving one positional parameter. It can also be a list/tuple of callables.
Returns:

nothing.
remove_callback(name, callback)[source]

Remove a callback from event name

bind_events(**events)[source]

Register all known events found in events key-valued parameters.

fire_event(name, *args, **kwargs)[source]

Dispatches arg or self to event name listeners.

  • If event at name is a one-time event, it makes sure that it was not fired before.
Parameters:
  • args – optional argument passed as positional parameter to the event handler.
  • kwargs – optional key-valued parameters to pass to the event handler. Can only be used for many times events.
Returns:

the Event fired
copy_many_times_events(other)[source]

Copy many times events from other.

All many times events of other are copied to this handler provided the events handlers already exist.