Observers¶
-
gtkmvc.observer.
observes
(*args)¶ Decorate a method in an
Observer
subclass as a notification. Takes one to many property names as strings. If any of them changes in a model we observe, the method is called. The name of the property will be passed to the method.The type of notification is inferred from the number of arguments. Valid signature are:
def value_notify(self, model, name, old, new) def before_notify(self, model, name, instance, method_name, args, kwargs) def after_notify(self, model, name, instance, method_name, res, args, kwargs) def signal_notify(self, model, name, arg)
New in version 1.99.0.
Deprecated since version 1.99.1: Use
Observer.observe()
instead, which offers more features.
-
class
gtkmvc.observer.
Observer
(model=None, spurious=False)¶ Note
Most methods in this class are used internally by the framework. Do not override them in subclasses.
model is passed to
observe_model()
if given.spurious indicates interest to be notified even when the value hasn’t changed, like for:
model.prop = model.prop
New in version 1.2.0: Before that observers had to filter out spurious notifications themselves, as if the default was True. With
Signal
support this is no longer necessary.-
get_custom_observing_methods
(prop_name)¶ An alias for
get_observing_methods()
.Deprecated since version 1.99.1.
-
accepts_spurious_change
()¶ Returns True if this observer is interested in receiving spurious value changes. This is queried by the model when notifying a value change.
-
get_observing_method_kwargs
(prop_name, method)¶ Returns the keyword arguments which were specified when declaring a notification method, either statically of synamically with
Observer.observe()
.method a callable that was registered with
observes()
.Return type: dict
-
get_observing_methods
(prop_name)¶ Return a possibly empty set of callables registered with
observe()
for prop_name.New in version 1.99.1: Replaces
get_custom_observing_methods()
.
-
is_observing_method
(prop_name, method)¶ Returns True if the given method was previously added as an observing method, either dynamically or via decorator.
-
classmethod
observe
(*f, **k)¶ Mark a method as recieving notifications. Comes in two flavours:
-
observe
(name, **types) A decorator living in the class. Can be applied more than once to the same method, provided the names differ.
name is the property we want to be notified about as a string.
types are boolean values denoting the types of notifications desired. At least one of the following has to be passed as True: assign, before, after, signal.
Excess keyword arguments are passed to the method as part of the info dictionary.
-
observe
(callable, name, **types) An instance method to define notifications at runtime. Works as above.
callable is the method to send notifications to. The effect will be as if this had been decorated.
In all cases the notification method must take exactly three arguments: the model object, the name of the property that changed, and an
NTInfo
object describing the change.Warning
Due to limitation in the dynamic registration (in version 1.99.1), declarations of dynamic notifications must occur before registering self as an observer of the models whose properties the notifications are supposed to be observing. A hack for this limitation, is to first relieve any interesting model before dynamically register the notifications, and then re-observe those models.
New in version 1.99.1.
-
-
observe_model
(model)¶ Starts observing the given model
-
relieve_model
(model)¶ Stops observing the given model
-
-
class
gtkmvc.observer.
NTInfo
(_type, *args, **kwargs)¶ Bases:
dict
A container for information attached to a notification. This class is a dictionary-like object used:
- As class when defining notification methods in observers, as it contains the flags identifying the notification types.
- As class instance as parameter when a notification methods is called in observers.
Notification Type Flags
Notification methods are declared either statically or dynamically through
Observer.observe()
. In both cases the type of the notification is defined by setting to True some flags. Flags can be set in any combination for multi-type notification methods. Flags are:- assign
- For notifications issued when OPs are assigned.
- before
- For notifications called before a modifying method is called.
- after
- For notifications called after a modifying method is called.
- signal
- For notifications called when a signal is emitted.
Instance content
Instances of class NTInfo will be received as the last argument (info) of any notification method:
def notification_method(self, model, name, info)
NTInfo is a dictionary (with some particular behaviour added) containing some information which is independent on the notification type, and some other information wich depends on the notification type.
Common to all types
For all notification types, NTInfo contains:
- model
- the model containing the observable property triggering the notification. model is also passed as first argument of the notification method.
- prop_name
- the name of the observable property triggering the notification. name is also passed as second argument of the notification method.
Furthermore, any keyword argument not listed here is copied without modification into info.
There are further information depending on the specific notification type:
For Assign-type
- assign
- flag set to True
- old
- the value that the observable property had before being changed.
- new
- the new value that the observable property has been changed to.
For Before method call type
- before
- flag set to True
- instance
- the object instance which the method that is being called belongs to.
- method_name
- the name of the method that is being called.
- args
- tuple of the arguments of the method that is being called.
- kwargs
- dictionary of the keyword arguments of the method that is being called.
For After method call type
- after
- flag set to True
- instance
- the object instance which the method that has been called belongs to.
- method_name
- the name of the method that has been called.
- args
- tuple of the arguments of the method that has been called.
- kwargs
- dictionary of the keyword arguments of the method that has been called.
- result
- the value returned by the method which has been called.
For Signal-type
- signal
- flag set to True
- arg
- the argument which was optionally specified when invoking emit() on the signal observable property.
Information access
The information carried by a NTInfo instance passed to a notification method can be retrieved using the instance as a dictionary, or accessing directly to the information as an attribute of the instance. For example:
# This is a multi-type notification @Observer.observe("op1", assign=True, hello="Ciao") @Observer.observe("op2", after=True, before=True) def notify_me(self, model, name, info): assert info["model"] == model # access as dict key assert info.prop_name == name # access as attribute if "assign" in info: assert info.old == info["old"] assert "hello" in info and "ciao" == info.hello print "Assign from", info.old, "to", info.new else: assert "before" in info or "after" in info assert "hello" not in info print "Method name=", info.method_name if "after" in info: print "Method returned", info.result pass return
As already told, the type carried by a NTInfo instance can be accessed through boolean flags assign, before, after and signal. Furthermore, any other information specified at declaration time (keyword argument ‘hello’ in the previous example) will be accessible in the corresponding notification method.
New in version 1.99.1.
-
__getattr__
(name)¶ All dictionary keys are also available as attributes.