pydispatch.properties
#
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)[source]#
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#
The name of the Property as defined in the class definition. This will match the attribute name for the
Dispatcher
instance.- Type
- _on_change(obj, old, value, **kwargs)[source]#
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 namekeys (optional) – If the
Property
is a container type (ListProperty
orDictProperty
), 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)[source]#
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 isFalse
(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)[source]#
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 isFalse
(for performance and memory reasons).
Changes to the contents of the dict are able to be observed through
ObservableDict
.
Observable class#
- class Observable[source]#
Mixin used by
ObservableList
andObservableDict
to emit changes and build other observablesWhen 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 anotherObservableDict
. This allows nested containers to be observed and their changes to be tracked.
ObservableList class#
- class ObservableList(initlist=None, **kwargs)[source]#
Bases:
list
,pydispatch.properties.Observable
A
list
subclass that tracks changes to its contentsNote
This class is for internal use and not intended to be used directly
ObservableDict class#
- class ObservableDict(initdict=None, **kwargs)[source]#
Bases:
dict
,pydispatch.properties.Observable
A
dict
subclass that tracks changes to its contentsNote
This class is for internal use and not intended to be used directly