cells.observer.Observer

Package cells :: Module observer :: Class Observer

Class Observer
source code

object --+
         |
        Observer

Wrapper for a function which fires when a Model updates and certain conditions are met. Observers may be bound to specific attributes or whether a function returns true when handed a cell's old value or new value, or any combination of the above. An observer that has no conditions on its running runs whenever the Model updates. Observers with multiple conditions will only fire when all the conditions pass. Observers run at most once per datapulse.

You should use the Model.observer decorator to add Observers to Models:

>>> import cells
>>> class A(cells.Model):
...     x = cells.makecell(value=4)
... 
>>> @A.observer(attrib="x",
...             newvalue=lambda a: a % 2)
... def odd_x_obs(model):
...     print "New value of x is odd!"
... 
>>> @A.observer(attrib="x")
... def x_obs(model):
...     print "x got changed!"
... 
>>> @A.observer()      
... def model_obs(model):
...     print "something in the model changed"
... 
>>> @A.observer(attrib="x",
...             newvalue=lambda a: a % 2,
...             oldvalue=lambda a: not (a % 2))
... def was_even_now_odd_x_obs(model):
...     print "New value of x is odd, and it was even!"
... 
>>> a = A()
something in the model changed
x got changed!

>>> a.x = 5
something in the model changed
x got changed!
New value of x is odd!
New value of x is odd, and it was even!

>>> a.x = 11
something in the model changed
x got changed!
New value of x is odd!

>>> a.x = 42
something in the model changed
x got changed!

Instance Methods	[hide private]

__init__(self, attrib, oldvalue, newvalue, func)
Initializes a new Observer.

run_if_applicable(self, model, attr)
Determine whether this observer should fire, and fire if appropriate.

Inherited from object: __delattr__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __str__

Class Variables	[hide private]

Inherited from object: __class__

Instance Variables	[hide private]

attrib (optional) The cell name this observer watches.

func The function to run when the observer fires.

last_ran The DP this observer last ran in.

newvalue A function (signature: f(val) -> bool) which, if it returns True when passed a changed cell's out-of-date value, allows the observer to fire.

oldvalue A function (signature: f(val) -> bool) which, if it returns True when passed a changed cell's out-of-date value, allows the observer to fire.

Method Details	[hide private]

init(self, attrib, oldvalue, newvalue, func)
(Constructor)

source code

Initializes a new Observer. All arguments are required, but only func is required to be anything but none.

See attrib, oldvalue, and newvalue instance variable docs for explanation of their utility.

Overrides: object.__init__

run_if_applicable(self, model, attr)

source code

Determine whether this observer should fire, and fire if appropriate.

Parameters:

model - the model instance to search for matching cells within.
attr - the attribute which "asked" this observer to run.

Instance Variable Details	[hide private]

attrib

(optional) The cell name this observer watches. Only when a cell with this name changes will the observer fire. You may also pass a list of cell names to "watch".

func

The function to run when the observer fires. Signature: f(model_instance) -> (ignored)

last_ran

The DP this observer last ran in. Observers only run once per DP.

newvalue

A function (signature: f(val) -> bool) which, if it returns True when passed a changed cell's out-of-date value, allows the observer to fire.

oldvalue