clubsandwich.event_dispatcher

Simple event dispatch system. It works like this:

class X:
  def __init__(self, name):
    self.name = name

  def on_foo(self, event):
    print("Fire foo on {}".format(name))

player = dict(id='player')
a = X('a')
b = X('b')
dispatcher = EventDispatcher()
dispatcher.register_event_type('foo')

# 'a.on_foo' gets called for all 'foo' events
dispatcher.add_subscriber(a, 'foo', None)
# 'b.on_foo' gets called only for events with `entity is player`
dispatcher.add_subscriber(b, 'foo', player)

dispatcher.fire('foo', None, None)  # prints 'a'
dispatcher.fire('foo', player, None)  # prints 'a' and 'b'

Note

Having used this in a game, I think I’m going to try something totally different next time. This class will probably be removed in the next release.

class clubsandwich.event_dispatcher.Event(name, entity, data)

name

Event name as registered in EventDispatcher.register_event_type()

entity

Entity associated with this event. May be None.

data

Arbitrary data passed to EventDispatcher.fire().

stop_propagation()

Prevent any more handlers for this event from firing

class clubsandwich.event_dispatcher.EventDispatcher

Collects and calls object methods in response to events.

For an event foo, your subscriber should have a method on_foo() and take one argument, an Event instance.

add_subscriber(obj, name, entity)

Parameters:

• obj (object) – Object to be called when the event fires
• name (str|Enum) – Name of the event. May be a string-valued enum.
• entity – If None, receive all events regardless of their entity. Otherwise, only receive events whose entity is this object.

Store (obj, entity) as a subscriber for the event name. When fire() is called with a pattern that matches (obj, entity), call obj.on_[name](Event(name, entity, data)).

An event is said to “match” a subscription if the subscription has the same event name, and either the subscriber’s entity is None, or the subscriber’s entity is the event’s entity.

You may subscribe more than once to receive the event multiple times.

fire(name, entity, data)

Parameters:

• obj (object) – Object that is subscribed
• name (str|Enum) – Name of the event. May be a string-valued enum.
• entity – Entity, or None.
• data – Arbitrary data to add to the Event.

Call all event handlers for the given name + entity, and pass data.

register_event_type(name)

Parameters:name (str|Enum) – Name of the event. May be a string-valued enum.

Allow events with the given name to be subscribed to and fired.

The dispatcher requires you to register events before using them to avoid typo-related errors.

remove_subscriber(obj, name, entity)

Parameters:

• obj (object) – Object that is subscribed
• name (str|Enum) – Name of the event. May be a string-valued enum.
• entity – Entity originally subscribed to

If you subscribed more than once with the same object/entity pair, you will need to unsubscribe more than once as well.

stop_propagation()

Prevent any more handlers for the active event from firing