Package pytilities :: Package event :: Module dispatcher' :: Class Dispatcher

Class Dispatcher

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

Class Dispatcher

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

__init__(self) (Constructor)

add_delegator_profile(name, profile)

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

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

event(self, event_name, owner=None)

has_event(self, event_name)

register_events(self, *event_names)

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

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

_delegator_factory

events

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

init(self)
(Constructor)