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
remove_observing_method(prop_names, method)

Remove dynamic notifications.

method a callable that was registered with observe().

prop_names a sequence of strings. This need not correspond to any one add call.

Note

This can revert the effects of a decorator at runtime. Don’t.

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:

  1. As class when defining notification methods in observers, as it contains the flags identifying the notification types.
  2. 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.

Previous topic

Observable Properties

Next topic

Little Helpers

This Page