pytilities.event.dispatcher_

exception pytilities.event.dispatcher_.UnsupportedEventError(event_name)

Tried to access an unregistered event

class pytilities.event.dispatcher_.Dispatcher

Utility class for dispatching events to handlers.

Events have to be registered before they can be dispatched or have handlers added to them.

Handlers can have an owner associated with them, usually you’ll use the reference of the listener. This allows you to remove all the handlers of a specific owner, which should save you some work.

Class invariants:
 
  • For every (owner, event), there can be only 0 or 1 handlers
add_handler(event_name, handler, owner=None)

Add handler for an event, optionally with an owner.

Parameters:
  • event_name (string) – name of the event to add the handler to
  • handler (callable) – the handler to call when the event is dispatched
  • owner – owner of the handler. Use this reference to easily remove all your handlers from the dispatcher (e.g. remove all handlers with the same owner). Default: None
Raises UnsupportedEventError:
 

when event_name doesn’t exist

dispatch(event_name, *args, **keyword_args)

Dispatch an event to its handlers.

The handlers are executed in a random order.

Parameters:
  • event_name (string) – name of the event to dispatch
  • args – arguments to pass to the handlers
  • keyword_args – keyword arguments to pass to the handlers
Raises UnsupportedEventError:
 

if event_name doesn’t exist

event(event_name, owner=None)

Register the decorated as a handler of event_name

Parameters:
  • event_name (string) – name of the event
  • owner – owner of the handler. Use this reference to easily remove all your handlers from the dispatcher (e.g. remove all handlers with the same owner). Default: None
has_event(event_name)

Checks if event_name is supported

Parameters:event_name (string) – name of the event
Returns:True if the dispatcher has the event
register_events(*event_names)

Register events.

Parameters:event_names ((string...)) – names of events to support
remove_handler(event_name, handler, owner=None)

Remove a handler from an event. It is an error to try to remove a handler from an event that doesn’t have this handler attached to it.

Parameters:
  • event_name (callable) – name of the event to which the handler belongs
  • handler – the handler that is attached to the event
  • owner – owner of the handler. Default: None
Preconditions :
  1. handler is attached to event_name
Raises UnsupportedEventError:
 

when event_name doesn’t exist

remove_handlers(event_name=None, owner=None)

Remove all or some handlers of the dispatcher.

event_name and owner act as filters of what to remove.

If no handler matched the criterea, the method will return silently.

Parameters:
  • event_name (string) – the event of which to remove the handlers. None means any. Default: None
  • owner – the owner of which to remove the handlers. None means any. Default: None
default_mapping = {('set', 'remove_handlers'): 'remove_handlers', ('set', 'register_events'): 'register_events', ('delete', 'events'): 'events', ('get', 'has_event'): 'has_event', ('delete', 'dispatch'): 'dispatch', ('get', 'dispatch'): 'dispatch', ('delete', 'has_event'): 'has_event', ('set', 'add_handler'): 'add_handler', ('delete', 'register_events'): 'register_events', ('set', 'events'): 'events', ('get', 'event'): 'event', ('delete', 'remove_handler'): 'remove_handler', ('get', 'register_events'): 'register_events', ('delete', 'event'): 'event', ('set', 'has_event'): 'has_event', ('get', 'remove_handlers'): 'remove_handlers', ('get', 'add_handler'): 'add_handler', ('delete', 'add_handler'): 'add_handler', ('delete', 'remove_handlers'): 'remove_handlers', ('set', 'remove_handler'): 'remove_handler', ('set', 'dispatch'): 'dispatch', ('set', 'event'): 'event', ('get', 'events'): 'events', ('get', 'remove_handler'): 'remove_handler'}
events

Read-only, set of all supported events

Return type:frozenset(string...)
public_mapping = {('set', 'remove_handlers'): 'remove_handlers', ('delete', 'events'): 'events', ('set', 'has_event'): 'has_event', ('get', 'remove_handlers'): 'remove_handlers', ('set', 'remove_handler'): 'remove_handler', ('get', 'has_event'): 'has_event', ('delete', 'add_handler'): 'add_handler', ('set', 'event'): 'event', ('delete', 'remove_handlers'): 'remove_handlers', ('delete', 'has_event'): 'has_event', ('get', 'add_handler'): 'add_handler', ('get', 'event'): 'event', ('delete', 'event'): 'event', ('set', 'add_handler'): 'add_handler', ('set', 'events'): 'events', ('get', 'events'): 'events', ('delete', 'remove_handler'): 'remove_handler', ('get', 'remove_handler'): 'remove_handler'}

Previous topic

pytilities.event

Next topic

pytilities.event.dispatcherswitch

This Page