API¶
pydispatch.dispatch module¶
-
class
Dispatcher
(*args, **kwargs)[source]¶ Bases:
object
Core class used to enable all functionality in the library
Interfaces with
Event
andProperty
objects upon instance creation.Events can be created by calling
register_event()
or by the subclass definition:class Foo(Dispatcher): _events_ = ['awesome_event', 'on_less_awesome_event']
Once defined, an event can be dispatched to listeners by calling
emit()
.-
bind
(**kwargs)[source]¶ Subscribes to events or to
Property
updatesKeyword arguments are used with the Event or Property names as keys and the callbacks as values:
class Foo(Dispatcher): name = Property() foo = Foo() foo.bind(name=my_listener.on_foo_name_changed) foo.bind(name=other_listener.on_name, value=other_listener.on_value)
The callbacks are stored as weak references and their order is not maintained relative to the order of binding.
-
emission_lock
(name)[source]¶ Holds emission of events and dispatches the last event on release
The context manager returned will store the last event data called by
emit()
and prevent callbacks until it exits. On exit, it will dispatch the last event captured (if any):class Foo(Dispatcher): _events_ = ['my_event'] def on_my_event(value): print(value) foo = Foo() foo.bind(my_event=on_my_event) with foo.emission_lock('my_event'): foo.emit('my_event', 1) foo.emit('my_event', 2) >>> 2
Parameters: name (str) – The name of the Event
orProperty
Returns: A context manager to be used by the with
statement.If available, this will also be an async context manager to be used with the
async with
statement (see PEP 492).Note
The context manager is re-entrant, meaning that multiple calls to this method within nested context scopes are possible.
-
emit
(name, *args, **kwargs)[source]¶ Dispatches an event to any subscribed listeners
Note
If a listener returns
False
, the event will stop dispatching to other listeners. Any other return value is ignored.Parameters:
-
register_event
(*names)[source]¶ Registers new events after instance creation
Parameters: *names (str) – Name or names of the events to register
-
unbind
(*args)[source]¶ Unsubscribes from events or
Property
updatesMultiple arguments can be given. Each of which can be either the method that was used for the original call to
bind()
or an instance object.If an instance of an object is supplied, any previously bound Events and Properties will be ‘unbound’.
-
pydispatch.properties module¶
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.
-
class
Property
(default=None)[source]¶ Bases:
object
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)[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 name - keys (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.
- property – The
-
-
class
ListProperty
(default=None, copy_on_change=False)[source]¶ Bases:
pydispatch.properties.Property
Property with a
list
type valueParameters: - 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
, thelist
will be copied when contents are modified. This can be useful for observing the original state of thelist
from within callbacks. The copied (original) state will be available from the keyword argument ‘old’. The default ifFalse
(for performance and memory reasons).
Changes to the contents of the list are able to be observed through
ObservableList
.- default (Optional) – If supplied, this will be the default value of the
Property for all instances of the class. Otherwise
-
class
DictProperty
(default=None, copy_on_change=False)[source]¶ Bases:
pydispatch.properties.Property
Property with a
dict
type valueParameters: - 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
, thedict
will be copied when contents are modified. This can be useful for observing the original state of thedict
from within callbacks. The copied (original) state will be available from the keyword argument ‘old’. The default ifFalse
(for performance and memory reasons).
Changes to the contents of the dict are able to be observed through
ObservableDict
.- default (Optional) – If supplied, this will be the default value of the
Property for all instances of the class. Otherwise