gale.event module
gale.event: a lightweight, decoupled publish/subscribe toolkit – Signal (a single, explicit event channel: connect/disconnect/emit, priority-ordered, connect(…, once=True) for a listener that detaches itself before it runs so it can safely reconnect from inside its own callback), EventEmitter (a mixin/composable object owning any number of ad hoc, string-named Signals created lazily on first use – on/off/once/emit), and EventBus, a ready-to-use global EventEmitter exposed as classmethods over a single module-level instance, the same shape gale.input_handler.InputHandler already uses for its own listeners – for cross-module communication that shouldn’t have to route through a shared object reference (gale.quest broadcasting “wolves_killed” for gale.ai or gale.ui to react to, without either one importing the other).
Every emit snapshots its listener list before iterating, so a listener that connects or disconnects another listener – or itself – from inside its own callback never corrupts the dispatch (the same defense InputHandler.notify already uses via listeners.copy()), and isolates each listener’s exceptions (logged through gale.log, never propagated) so one broken subscriber can never break every other, independently owned listener on the same event. That is a deliberately stricter contract than InputHandler.notify’s fail-fast one: InputHandler always routes to a single active entity, while an event here is a fan-out to an arbitrary number of unrelated, independently owned listeners, where one of them breaking should never take the rest down with it.
See docs/examples/event.rst for a walkthrough.
Author: Alejandro Mujica (aledrums@gmail.com)
- class gale.event.Signal[source]
Bases:
objectA single event channel. Holds no notion of a name or an owner – just the list of listeners connected to it – so it can be used directly as an attribute (
died = Signal()) or driven dynamically by EventEmitter/EventBus.- connect(listener, *, once=False, priority=0)[source]
- Parameters:
listener (Callable[[...], Any]) – A callable invoked with whatever positional/keyword arguments emit() is given.
once (bool) – If True, listener is disconnected right before it runs its first time, so a single emit() call never reaches it twice. The default value is False.
priority (int) – Listeners with a higher priority run first; listeners sharing a priority run in the order they were connected. The default value is 0.
- Raises:
ValueError – If listener is already connected – almost always a sign of a missing disconnect() paired with an enter()/setup() that runs more than once.
- Return type:
None
- disconnect(listener)[source]
Remove listener. A silent no-op if it was never connected (or already disconnected), the same tolerance InputHandler.unregister_listener gives.
- Parameters:
listener (Callable[[...], Any])
- Return type:
None
- emit(*args, **kwargs)[source]
Call every connected listener with args/kwargs, highest priority first (ties keep connection order). Snapshots the listener list up front, so a listener that connects or disconnects another listener (including itself) never corrupts this dispatch: a disconnected once listener is skipped if it hasn’t run yet, and a newly connected listener only takes part in the next emit(). A listener that raises has the exception logged and dispatch continues – one broken subscriber never stops the rest from being notified.
- Parameters:
args (Any)
kwargs (Any)
- Return type:
None
- class gale.event.EventEmitter(*args, **kwargs)[source]
Bases:
objectMixin/composable object owning an open-ended set of string-named Signal channels, created lazily the first time each name is used. Combine it by multiple inheritance the way InputListener/ CommandControlled are combined today, or hold one as a plain attribute wherever inheritance doesn’t fit (a World, a QuestLog, a net Server/Client, …).
- Parameters:
args (Any)
kwargs (Any)
- signal(event_name)[source]
The Signal backing event_name, creating it on first use. Exposed so callers that need it (len(), is_connected(), …) don’t have to go through on/off/emit for everything.
- Parameters:
event_name (str)
- Return type:
- on(event_name, listener, *, once=False, priority=0)[source]
- Parameters:
event_name (str)
listener (Callable[[...], Any])
once (bool)
priority (int)
- Return type:
None
- once(event_name, listener, *, priority=0)[source]
- Parameters:
event_name (str)
listener (Callable[[...], Any])
priority (int)
- Return type:
None
- off(event_name, listener)[source]
Silent no-op if event_name was never used, or listener was never connected to it.
- Parameters:
event_name (str)
listener (Callable[[...], Any])
- Return type:
None
- is_on(event_name, listener)[source]
- Parameters:
event_name (str)
listener (Callable[[...], Any])
- Return type:
bool
- class gale.event.EventBus[source]
Bases:
objectReady-to-use global EventEmitter, exposed as classmethods over a single module-level instance – the same shape InputHandler gives its own listeners – for modules that want to publish/subscribe without sharing an object reference to do it.
- classmethod on(event_name, listener, *, once=False, priority=0)[source]
- Parameters:
event_name (str)
listener (Callable[[...], Any])
once (bool)
priority (int)
- Return type:
None
- classmethod once(event_name, listener, *, priority=0)[source]
- Parameters:
event_name (str)
listener (Callable[[...], Any])
priority (int)
- Return type:
None
- classmethod off(event_name, listener)[source]
- Parameters:
event_name (str)
listener (Callable[[...], Any])
- Return type:
None
- classmethod is_on(event_name, listener)[source]
- Parameters:
event_name (str)
listener (Callable[[...], Any])
- Return type:
bool