Warning: This document is for the development version of python-dispatch. The latest version is v0.1.1.

pydispatch.properties module

Property objects can be defined on subclasses of Dispatcher to create instance attributes that act as events when their values change:

from pydispatch import Dispatcher, Property

class Foo(Dispatcher):
    name = Property()
    value = Property()
def __str__(self):
    return self.__class__.__name__

class Listener(object):
    def on_foo_name(self, instance, value, **kwargs):
        print("{}'s name is {}".format(instance, value))
    def on_foo_value(self, instance, value, **kwargs):
        print('{} = {}'.format(instance, value))

foo_obj = Foo()
listener_obj = Listener()

foo_obj.bind(name=listener_obj.on_foo_name, value=listener_obj.on_foo_value)

foo_obj.name = 'bar'
# Foo's name is bar

foo_obj.value = 42
# Foo = 42

Type checking is not enforced, so values can be any valid python type. Values are however checked for equality to avoid dispatching events for no reason. If custom objects are used as values, they must be able to support equality checking. In most cases, this will be handled automatically.

Property class

class Property(default=None)

Defined on the class level to create an observable attribute

Parameters:default (Optional) – If supplied, this will be the default value of the Property for all instances of the class. Otherwise None

name

str – The name of the Property as defined in the class definition. This will match the attribute name for the Dispatcher instance.

_on_change(obj, old, value, **kwargs)

Called internally to emit changes from the instance object

The keyword arguments here will be passed to callbacks through the instance object’s emit() method.

Keyword Arguments:  

• property – The Property instance. This is useful if multiple properties are bound to the same callback. The attribute name
• keys (optional) – If the Property is a container type (ListProperty or DictProperty), the changes may be found here. This is not implemented for nested containers and will only be available for operations that do not alter the size of the container.

ListProperty class

class ListProperty(default=None, copy_on_change=False)

Bases: pydispatch.properties.Property

Property with a list type value

Parameters:

• default (Optional) – If supplied, this will be the default value of the Property for all instances of the class. Otherwise None
• copy_on_change (bool, optional) – If True, the list will be copied when contents are modified. This can be useful for observing the original state of the list from within callbacks. The copied (original) state will be available from the keyword argument ‘old’. The default is False (for performance and memory reasons).

Changes to the contents of the list are able to be observed through ObservableList.

DictProperty class

class DictProperty(default=None, copy_on_change=False)

Bases: pydispatch.properties.Property

Property with a dict type value

Parameters:

• default (Optional) – If supplied, this will be the default value of the Property for all instances of the class. Otherwise None
• copy_on_change (bool, optional) – If True, the dict will be copied when contents are modified. This can be useful for observing the original state of the dict from within callbacks. The copied (original) state will be available from the keyword argument ‘old’. The default is False (for performance and memory reasons).

Changes to the contents of the dict are able to be observed through ObservableDict.

Observable class

class Observable

Mixin used by ObservableList and ObservableDict to emit changes and build other observables

When an item is added to an observable container (a subclass of Observable) it is type-checked and, if possible replaced by an observable version of it.

In other words, if a dict is added to a ObservableDict, it is copied and replaced by another ObservableDict. This allows nested containers to be observed and their changes to be tracked.

ObservableList class

class ObservableList(initlist=None, **kwargs)

Bases: list, pydispatch.properties.Observable

A list subclass that tracks changes to its contents

Note

This class is for internal use and not intended to be used directly

ObservableDict class

class ObservableDict(initdict=None, **kwargs)

Bases: dict, pydispatch.properties.Observable

A dict subclass that tracks changes to its contents

Note

This class is for internal use and not intended to be used directly