Package pytilities :: Package event :: Module dispatcher' :: Class Dispatcher
[hide private]
[frames] | no frames]

Class Dispatcher

source code

object --+
         |
        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.

Instance methods:

    - `add_handler`: Add handler for an event
    - `remove_handlers`: Remove all or some handlers
    - `remove_handler`: Remove a handler
    - `dispatch`: Dispatch an event
    - `register_events`: Register events
    - `has_event`: Check whether event is supported

Instance properties:

    - `events`: Read-only, set of all supported events

Instance decorators:

    - `event`: Register decorated as a handler

Class invariants:

    - For every (owner, event), there can be only 0 or 1 handlers

Instance Methods [hide private]
 
Delegator(profile_name='default', target=None)
Construct a delegator with a stored `Profile`.
source code
 
__init__(self)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature
source code
 
__remove_handlers(self, event, owner)
Remove handlers of single event, optionally with particular owner
source code
 
add_delegator_profile(name, profile)
Add a new delegator factory `Profile` to the factory.
source code
 
add_handler(self, event_name, handler, owner=None)
Add handler for an event, optionally with an owner.
source code
 
dispatch(self, event_name, *args, **keyword_args)
Dispatch an event to its handlers.
source code
 
event(self, event_name, owner=None)
Register the decorated as a handler of `event_name`
source code
 
has_event(self, event_name)
Checks if `event_name` is supported
source code
 
register_events(self, *event_names)
Register events.
source code
 
remove_handler(self, event_name, handler, owner=None)
Remove a handler from an event.
source code
 
remove_handlers(self, event_name=None, owner=None)
Remove all or some handlers of the dispatcher.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Static Methods [hide private]
 
__init_delegation_profiles(profiles) source code
Class Variables [hide private]
  _delegator_factory = <pytilities.delegation.delegatorfactory.D...
Properties [hide private]
  events
Read-only, set of all supported events

Inherited from object: __class__

Method Details [hide private]

Delegator(profile_name='default', target=None)

source code 

Construct a delegator with a stored `Profile`.

Parameters:

    `profile_name` :: string
        name of the `Profile` to use to set up the delegator with

    `target` = None
        target of the newly created delegator

Returns newly created delegator :: Delegator

Raises:

    - `ValueError` when no profile with name `profile_name` exists

__init__(self)
(Constructor)

source code 

x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Overrides: object.__init__
(inherited documentation)

add_delegator_profile(name, profile)

source code 

Add a new delegator factory `Profile` to the factory.

Parameters:

    `name` :: string
        name of the profile

    `profile` :: Profile
        the profile to add

add_handler(self, event_name, handler, owner=None)

source code 

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 = None
        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)

Raises:

    - `UnsupportedEventError` when `event_name` doesn't exist

dispatch(self, event_name, *args, **keyword_args)

source code 

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` when `event_name` doesn't exist

event(self, event_name, owner=None)

source code 

Register the decorated as a handler of `event_name`

Parameters:

    event_name :: string
        name of the event

    owner = None
        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)

has_event(self, event_name)

source code 

Checks if `event_name` is supported

Parameters:

    event_name :: string
        name of the event

Returns True if the dispatcher has the event

register_events(self, *event_names)

source code 

Register events.

Parameters:

    event_names :: (string...)
        names of events to support

remove_handler(self, event_name, handler, owner=None)

source code 

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 :: string
        name of the event to which the handler belongs

    handler :: callable
        the handler that is attached to the event

    owner = None
        owner of the handler

Preconditions:
    1. `handler` is attached to `event_name`

Raises:
    - `UnsupportedEventError` when `event_name` doesn't exist

remove_handlers(self, event_name=None, owner=None)

source code 

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 = None
        the event of which to remove the handlers. `None` means any

    owner = None
        the owner of which to remove the handlers. `None` means any


Class Variable Details [hide private]

_delegator_factory

Value:
<pytilities.delegation.delegatorfactory.DelegatorFactory object at 0x1\
770690>

Property Details [hide private]

events


Read-only, set of all supported events

Returns ::frozenset(string...)

Get Method:
unreachable.events(self) - Read-only, set of all supported events