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.
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.
An alias for get_observing_methods().
Deprecated since version 1.99.1.
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 |
---|
Return a possibly empty set of callables registered with observe() for prop_name.
New in version 1.99.1: Replaces get_custom_observing_methods().
Mark a method as recieving notifications. Comes in two flavours:
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.
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.
Bases: dict
A container for information attached to a notification. This class is a dictionary-like object used:
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:
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:
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
For Before method call type
For After method call type
For Signal-type
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.