pytilities.event.dispatcher'.Dispatcher

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