Larch-Reactive by Examples

This chapter introduces every feature of larch.reactive, by providing an example. Sections marked with describe the internals of larch.reactive and can be skipped. But keep in mind, if you want to get a real deep insight view: read the code.

Creating Reactive Classes, Cells, Rules

Lets come back to the first example. larch.reactive implements the observer pattern to connect rules (observer) to cells (subject).

>>> import larch.reactive as ra
>>> from datetime import datetime, timedelta
>>> 
>>> @ra.reactive
... class Task(object):
...     start = ra.Cell(datetime.now())
...     end = ra.Cell()
...     duration = ra.Cell(timedelta(hours=3))
...     prev = ra.Cell()
...     desc = ra.Cell("")
...     
...     @ra.rule
...     def _rule_start(self):
...         if self.prev:
...             self.start = self.prev.end
...     
...     @ra.rule
...     def _rule_end(self):
...         self.end = self.start + self.duration
...     
...     def __repr__(self):
...         return "'{}': {} -> {}".format(self.desc, self.start, self.end)
... 
>>> read = Task(desc="read tutorial", start=datetime(2016, 1, 9, 8),
...             duration=timedelta(hours=2))
>>> read
'read tutorial': 2016-01-09 08:00:00 -> 2016-01-09 10:00:00
>>> write = Task(desc="write own programs", prev=read)
>>> write
'write own programs': 2016-01-09 10:00:00 -> 2016-01-09 13:00:00
>>> read.duration = timedelta(hours=3)
>>> read
'read tutorial': 2016-01-09 08:00:00 -> 2016-01-09 11:00:00
>>> write
'write own programs': 2016-01-09 11:00:00 -> 2016-01-09 14:00:00

Line 4:

The reactive() decorator transforms an “ordinary” python class to a “reactive” class.

Lines 6-10:

Attributes that can be watched by rules must be declared as Cell. A Cell can have a default value by providing an argument while construction. By default cells are initialized with None.

Line 12, 17:

The rule() decorator transforms an “ordinary” python method to a rule, that is able to observe cells. Whenever a rule is executed, reading a cell’s value, registers the rule as observer for that cell. When such a cell changes its value, the rule is executed again.

Line 24:

Cells can be initialized by using keyword arguments, while constructing a reactive object.

larch.reactive extends the class __init__ and add the following functionality:

1. For each cell a Container is created, that stores the cell’s value and acts as subject.

2. For each rule an Observer object is created calling the rule method, when the observer is notified.

3. All rules are executed for the first time in their order of appearance.

Line 31:

Changing a cells value will execute all rules observing the cell.

Note

After several years of using the larch.reactive-library some best practice clues have been evolved:

• keep rules short

• try to avoid calling functions. Often this can lead to hidden dependencies, if the function accidently read unwanted cells. If you have to call function use the yield mechanism.

Internals of write

The following diagramm shows the internal state of write at line 34. (For more in depth information read the code in pcore.py)

Each Cell attribute is a descriptor that stores its value in a Container object. write has an attribute __reactive_state__ containing a list of all Containers

For each rule method a Rule object is created and internally stored in the __reactive_rules__ attribute.

Each Container stores a list of its observers:

• _rule_end observes write.start and write.duration.

• _rule_start observes write.prev and read.end.

Object interaction

The following diagramms show the object interaction at line 31. (For more in depth information read the code in pcore.py)

rcontext is the short form of “reactive context”. It is a global singleton object managing the internal event system of larch.reactive.

1. When Cell attribute (in this case duration) is changed the Container calls emit of rcontext.

2. rcontext enters an atomic stage.

Cell types

While working with larch.reactive it turned out it is convenient to have some more Cell objects.

TypeCell is used to ensure the cell’s value has a specific type:

>>> @ra.reactive
... class Point(object):
...     x = ra.TypeCell(0)
...     y = ra.TypeCell(0, converter=float)
... 
>>> p = Point(x="1", y="2")
>>> p.x
1
>>> p.y
2.0

MakeCell constructs the default attribute by calling a constructor:

>>> @ra.reactive
... class ListContainer(object):
...     values = ra.MakeCell(list, (1, 2, 3))
... 
>>> lc = ListContainer()
>>> lc.values
[1, 2, 3]

Keep in mind: For each new ListContainer object a new list is created.

Pointers

A small observer class can be used to inspect cell attributes of an object.

>>> @ra.reactive
... class StartObserver(object):
...     subject = ra.Cell()
...     
...     @ra.rule
...     def _rule_print(self):
...         print("start:", self.subject.start)
... 
>>> observer = StartObserver(subject=write)
start: 2016-01-09 11:00:00
>>> read.start += timedelta(hours=0.5)
start: 2016-01-09 11:30:00
>>> del observer  # deactivate observer

Remember that all rules will be called at construction, therefore the start attribute is printed while the StartObserver is created. The StartObserver class is not very flexible, it can only monitor start attributes. Here is a better observer:

>>> @ra.reactive
... class ProxyObserver(object):
...     subject = ra.Cell()
...     
...     @ra.rule
...     def _rule_print(self):
...         print("attribute:", repr(self.subject), self.subject())
... 
>>> observer = ProxyObserver(subject=ra.Proxy(write).start)
attribute: <Proxy-'write own programs': 2016-01-09 11:30:00 -> 2016-01-09 14:30:00.start> 2016-01-09 11:30:00
>>> read.start += timedelta(hours=0.5)
attribute: <Proxy-'write own programs': 2016-01-09 12:00:00 -> 2016-01-09 15:00:00.start> 2016-01-09 12:00:00

A Pointer acts like a pointer in the C language. An expression like ra.Pointer(write).start points to the attribute start of object write. To get the value of a pointer you have to call it: ra.Pointer(write).start().

>>> ra.Proxy(write).start() == write.start
True

You can also set an attribute value through a pointer:

>>> ra.Proxy(read).start(datetime(2016, 2, 9, 11))
attribute: <Proxy-'write own programs': 2016-02-09 14:00:00 -> 2016-02-09 17:00:00.start> 2016-02-09 14:00:00

Pointers can not only point to simple attributes but to whole expressions:

>>> # prints write.start + 30min
>>> observer = ProxyObserver(subject=ra.Proxy(write).start + timedelta(minutes=30))
attribute: <Proxy-add('write own programs': 2016-02-09 14:00:00 -> 2016-02-09 17:00:00.start, datetime.timedelta(0, 1800))> 2016-02-09 14:30:00
>>> 
>>> # prints the maximum of read.end and write.end
>>> observer = ProxyObserver(subject=ra.ProxyExpression.call(
...     max, ra.Proxy(read).end, ra.Proxy(write).end))
attribute: <Proxy-max('read tutorial': 2016-02-09 11:00:00 -> 2016-02-09 14:00:00.end, 'write own programs': 2016-02-09 14:00:00 -> 2016-02-09 17:00:00.end)> 2016-02-09 17:00:00
>>> del observer  # deactivate observer

Last not least an improved version of the task example.

>>> @ra.reactive
... class ProxyTask(object):
...     start = ra.TypeCell(ra.Proxy(datetime.now()), converter=ra.Proxy)
...     end = ra.Cell()
...     duration = ra.TypeCell(ra.Proxy(timedelta(hours=3)), converter=ra.Proxy)
...     desc = ra.Cell("")
...     
...     @ra.rule
...     def _rule_end(self):
...         self.end = self.start() + self.duration()
...     
...     def __repr__(self):
...         return "'{}': {} -> {}".format(self.desc, self.start(), self.end)
... 
>>> pread = ProxyTask(desc="read tutorial", start=datetime(2016, 1, 9, 8),
...                   duration=timedelta(hours=2))
>>> pwrite = ProxyTask(desc="write own programs", start=ra.Proxy(pread).end)
>>> pread
'read tutorial': 2016-01-09 08:00:00 -> 2016-01-09 10:00:00
>>> pwrite
'write own programs': 2016-01-09 10:00:00 -> 2016-01-09 13:00:00

TypeCell is used for start and duration to ensure they contain pointers. The prev attribute is not needed anymore, the dependencies are created by pointers.

Note

The features of pointers:

• Pointers will be evaluated when you call them.

• Pointers can point to whole expressions.

• The value of simple pointers can be set by calling the pointers with the new value.

Trivial Delegator

The implementation of pointers offers a simple mechanism for a trivial delegator:

>>> @ra.reactive
... class TaskPrinter(object):
...     task = ra.Cell()
...     # make task attributes to my own
...     start = ra.SELF.task.start
...     end = ra.SELF.task.end
...     desc = ra.SELF.task.desc
...     
...     @ra.rule
...     def _rule_print(self):
...         print("'{}': {} -> {}".format(self.desc, self.start, self.end))
... 
>>> printer = TaskPrinter(task=write)
'write own programs': 2016-02-09 14:00:00 -> 2016-02-09 17:00:00
>>> del printer  # deactivate printer

Contexts

Changing cell attributes can be influenced by contexts. Context’s can also be used as decorators.

atomic()

Changing cells within an atomic context, will postpone the call of rules after the context finishes:

>>> printer = TaskPrinter(task=read)
'read tutorial': 2016-02-09 11:00:00 -> 2016-02-09 14:00:00
>>> 
>>> read.start = datetime(2016, 1, 8, 8)
'read tutorial': 2016-01-08 08:00:00 -> 2016-01-08 11:00:00
>>> read.duration = timedelta(hours=2)
'read tutorial': 2016-01-08 08:00:00 -> 2016-01-08 10:00:00
>>> 
>>> with ra.atomic():
...     read.start = datetime(2016, 1, 9, 8)
...     read.duration = timedelta(hours=3)
... 
'read tutorial': 2016-01-09 08:00:00 -> 2016-01-09 11:00:00
>>> del printer  # deactivate printer

Line 4-7:

Every change will result in a immediate reactive reaction.

Line 9-13:

Within an atomic context, the rules are called after the context ends.

Note

Features of atomic contexts

• rules are executed in an atomic context

• in a gevent environment only one greenlet can execute an atomic context.

If another greenlet wants to execute an atomic context it will be locked until the previous context has finished.

untouched()

Rules will connect to a all cells read by the rule. Sometimes you want to avoid this:

>>> @ra.reactive
... class SillyTaskPrinter(object):
...     task = ra.Cell()
...     
...     @ra.rule
...     def _rule_print(self):
...         # this rule does not depend on self.task.end
...         with ra.untouched():
...             end = self.task.end
...         print("'{}': {} -> {}".format(self.task.desc, self.task.start, end))
... 
>>> printer = SillyTaskPrinter(task=read)
'read tutorial': 2016-01-09 08:00:00 -> 2016-01-09 11:00:00
>>> read.duration = timedelta(hours=2.5)
>>> read.start = datetime(2016, 1, 8, 8)
'read tutorial': 2016-01-08 08:00:00 -> 2016-01-09 10:30:00
>>> 
>>> del printer  # deactivate printer

In line 14, the change of duration will trigger a change of end, but SillyTaskPrinter._rule_print does not depend on end, therefore nothing is printed.

Warning

You should use this context only, if there is no other solution. It often signals bad practice.

silent()

If you want to change a cell without initiating the reactive reaction:

>>> with ra.silent():
...     read.start = datetime(2016, 1, 9, 8)
... 
>>> read
'read tutorial': 2016-01-09 08:00:00 -> 2016-01-08 10:30:00
>>> 
>>> read._rule_end()
>>> read
'read tutorial': 2016-01-09 08:00:00 -> 2016-01-09 10:30:00

Line 1:

The silent context disables the reactive behaviour.

Line 4:

read is in an inconsistent state: start > end.

Line 7:

Calling the rule manually updates the depended attributes.

Warning

You should use this context only, if there is no other solution. It often signals bad practice.

yield rules

Often rules should trigger a function with a big bunch of operations. Such a function should be called outside the atomic context to ensure:

• the rule should not depend on unwanted cells used in the function

• in gevent environments the function should not lock other greenlets by locking the atomic context.

Therefore rules can be written as co-routines:

>>> @ra.reactive
... class TaskObserver(object):
...     task = ra.Cell()
...     
...     @ra.rule
...     def _rule_trigger_action(self):
...         self.task.end  # touch without using the value
...         yield
...         # many operations using different cells
...         # the rule does not depend on these cells

The yield separates a rule into an atomic part above the yield and an operational part after yield.

Rule Order

At construction rules are called in the order of their appearance.

>>> @ra.reactive
... class RuleOrderDemo(object):
...     a = ra.Cell(0)
...     b = ra.Cell(0)
...     c = ra.Cell(0)
...     
...     @ra.rule
...     def _rule_first(self):
...         self.c = self.b + 1
...         print("rule first is called c =", self.c)
...     
...     @ra.rule
...     def _rule_second(self):
...         self.b = self.a + 1
...         print("rule second is called b =", self.b)
... 
>>> demo = RuleOrderDemo()
rule first is called c = 1
rule second is called b = 1
rule first is called c = 2
>>> demo.a, demo.b, demo.c
(0, 1, 2)

As you can see _rule_first is called two times because “_rule_second” changes b and c must be updated. An internal optimization mechanism, rearranges the call order, to minimize the count of rule calls:

>>> demo.a = 2
rule second is called b = 3
rule first is called c = 4

larch.reactive can be forced to obey a call order by using the rule() with a parameter.

>>> @ra.reactive
... class RuleOrderDemo(object):
...     a = ra.Cell(0)
...     b = ra.Cell(0)
...     c = ra.Cell(0)
...     
...     @ra.rule(2)
...     def _rule_first(self):
...         self.c = self.b + 1
...         print("rule first is called c =", self.c)
...     
...     @ra.rule(1)
...     def _rule_second(self):
...         self.b = self.a + 1
...         print("rule second is called b =", self.b)
... 
>>> demo = RuleOrderDemo()
rule second is called b = 1
rule first is called c = 2

Agents

To inspect internals of a cell agents can be used.

old()

Within a rule old() delivers the value before the cell was changed:

>>> @ra.reactive
... class TaskPrinter(object):
...     task = ra.Cell()
...     
...     @ra.rule
...     def _rule_print(self):
...         otask = ra.old(self.task)
...         if otask.start == self.task.start and otask.end == self.task.end:
...             return
...         print("'{}': {}({}) -> {}({})".format(
...             self.task.desc, self.task.start, otask.start,
...             self.task.end, otask.end))
... 
>>> printer = TaskPrinter(task=read)
>>> read.start = datetime(2016, 1, 8, 8)
'read tutorial': 2016-01-08 08:00:00(2016-01-09 08:00:00) -> 2016-01-08 10:30:00(2016-01-09 10:30:00)
>>> del printer  # deactivate printer

Line 7:

The otask object has the same cell attributes as self.task but their values are the values before the atomic context was entered.

Line 8:

Only print if the values have changed.

Note

The Lifetime of Reactive objects

In line 17 the the printer is deactivated. This is because inside the reactive framework all references to objects are weakrefs. If an object is garbage collected all “cell to rule” connections will be also destroyed.

cell()

The cell() agent delivers the internal Container object of the cell

>>> cread = ra.cell(read)
>>> cread.end
<Container(7fc2247a1ca8: datetime.datetime(2016, 1, 8, 10, 30)>
>>> cread.end.get_observers()
[<Rule _rule_start(0, 60) of 'write own programs': 2016-01-08 10:30:00 -> 2016-01-08 13:30:00>]
>>> cread.end.get_value()
datetime.datetime(2016, 1, 8, 10, 30)

The cread object has the same cell attributes as self.task but their values point to the Container objects, containing their value.

Collections

larch.reactive provides subclasses of some standard mutable containers.

List()

A list that fires events when it is changed. It provides two reactive “event”-attributes: __action_start__ is set before the list is changed, and __action_end__ is set after the list has changed.

>>> @ra.reactive
... class ContainerObserver(object):
...     subject = ra.Cell()
...     
...     @ra.rule
...     def _rule_print_start(self):
...         print("action start:", self.subject.__action_start__)
...     
...     @ra.rule
...     def _rule_print_end(self):
...         print("action end:", self.subject.__action_end__)
... 
>>> from larch.reactive.rcollections import List
>>> container = List()
>>> observer = ContainerObserver(subject=container)
action start: None
action end: None
>>> 
>>> container.append(1)
action start: ('insert', (0, 1))
action end: ('insert', (0, 1))
>>> 
>>> container[0] = 2
action start: ('change', (slice(0, 1, None), [2]))
action end: ('change', (slice(0, 1, None), [2]))
>>> 
>>> container[:] = [1, 2, 3]
action start: ('change', (slice(0, 1, None), [1, 2, 3]))
action end: ('change', (slice(0, 1, None), [1, 2, 3]))
>>> 
>>> container.reverse()
action start: ('order', 'reverse')
action end: ('order', 'reverse')
>>> 
>>> container.sort()
action start: ('order', 'sort')
action end: ('order', 'sort')
>>> 
>>> container += [4, 5, 6]
action start: ('extend', [4, 5, 6])
action end: ('extend', [4, 5, 6])
>>> 
>>> container *= 2
action start: ('imul', 2)
action end: ('imul', 2)
>>> 
>>> del container[2:-2]
action start: ('delete', slice(2, 10, None))
action end: ('delete', slice(2, 10, None))

The example shows what you have to expect in the action attributes: Their value is always None, if no event occurs. When the list is changed first __action_start__ is fired than __action_end__ is fired. The event is always a pair with the event type at the first place and informations about the event in the second place.

Dict()

Equally to List Dict is a reactive dictionary. It provides two reactive “event”-attributes: __action_start__ is set before the dictionary is changed, and __action_end__ is set after the list has changed.

>>> from larch.reactive.rcollections import Dict
>>> container = Dict()
>>> observer = ContainerObserver(subject=container)
action start: None
action end: None
>>> 
>>> container[1] = "one"
action start: ('change', (1, 'one'))
action end: ('change', (1, 'one'))
>>> 
>>> container.update({2: "two", 3: "three"})
action start: ('update', (({2: 'two', 3: 'three'},), {}))
action end: ('update', (({2: 'two', 3: 'three'},), {}))
>>> 
>>> container.popitem()
action start: ('delete', 1)
action end: ('delete', 1)
(1, 'one')
>>> 
>>> container.clear()
action start: ('clear', None)
action end: ('clear', None)

Pickle

The reactive base class SimpleReactive() defines the standard pickle methods __getstate__ and __setstate__ to pickle the cells values by default.

Threading

Reactive classes are not thread save but the state of an ReactiveContext is thread local.

This means: As long every Reactive object is used by only one thread you can work with several isolated threads. In Microsoft COM this is called Apartment Threading Model.

Debugging Helpers

Sometimes you got stuck, wondering why a rule is called. (Often because the best practice tips have been ignored). larch.reactive provides some helper functions to find out what is going on:

>>> import os
>>> os.environ["LARCH_REACTIVE"] = "python"
>>> import larch.reactive as ra
>>> import larch.reactive.debug as debug
>>> from datetime import datetime, timedelta
>>>
>>> @ra.reactive
... class Task(object):
...     start = ra.Cell(datetime.now())
...     end = ra.Cell()
...     duration = ra.Cell(timedelta(hours=3))
...     prev = ra.Cell()
...     desc = ra.Cell("")
...
...     @ra.rule
...     def _rule_start(self):
...         if self.prev:
...             self.start = self.prev.end
...
...     @ra.rule
...     def _rule_end(self):
...         self.end = self.start + self.duration
...
...     def __repr__(self):
...         return "'{}'".format(self.desc)
...
>>> read = Task(desc="read tutorial", start=datetime(2016, 1, 9, 8),
...             duration=timedelta(hours=2))
>>> write = Task(desc="write own programs", prev=read)
>>>
>>> print(debug.dump(read))
cells of 'read tutorial'
  start(Cell-5726ac8)
    <Rule _rule_end(0, 2) of 'read tutorial'>(5826598)
  end(Cell-5726cc8)
    <Rule _rule_start(0, 3) of 'write own programs'>(58266d8)
  duration(Cell-57268c8)
    <Rule _rule_end(0, 2) of 'read tutorial'>(5826598)
  prev(Cell-5726a48)
    <Rule _rule_start(0, 1) of 'read tutorial'>(5826548)

The dump function of larch.reactive.debug inspects a reactive object and prints for each cell the rules depending on that cell.

Note

larch.reactive has a fast cython implementation that is imported by default, and a pure python implementation as fallback. The debugging helpers only work with the pure python implementation! Setting os.environ[“LARCH_REACTIVE”] = “python” before(!) import larch.reactive will force to use the pure python version.

Within a debug context you atomic action are logged to a stream (by default sys.stderr)

>>> # from io import StringIO
>>> from io import BytesIO as StringIO
>>> out = StringIO()
>>>
>>> with debug.debug(output=out):
...     read.start += timedelta(hours=0.5)
...
>>> print(out.getvalue())
emit(1) <console>(2): ''
  (<Rule _rule_end(0, 2) of 'read tutorial'>,)

call rule <Rule _rule_end(0, 5) of 'read tutorial'>
  touch ('read tutorial'.<Cell start(1/0)>)
    _rule_end in <console>(16): ''

  touch ('read tutorial'.<Cell duration(0/2)>)
    _rule_end in <console>(16): ''

    emit(2) <console>(16): ''
      (<Rule _rule_start(0, 3) of 'write own programs'>,)


call rule <Rule _rule_start(0, 6) of 'write own programs'>
  touch ('write own programs'.<Cell prev(2/3)>)
    _rule_start in <console>(11): ''

  touch ('write own programs'.<Cell prev(2/3)>)
    _rule_start in <console>(12): ''

  touch ('read tutorial'.<Cell end(3/1)>)
    _rule_start in <console>(12): ''

    emit(2) <console>(12): ''
      (<Rule _rule_end(0, 4) of 'write own programs'>,)


call rule <Rule _rule_end(0, 7) of 'write own programs'>
  touch ('write own programs'.<Cell start(1/0)>)
    _rule_end in <console>(16): ''

  touch ('write own programs'.<Cell duration(0/2)>)
    _rule_end in <console>(16): ''

This is how you have to read the output:

Line 9:

The “emit” commands says that some reactive rules will be called. In a real program you will see the source file name and line instead of <console>(2): ‘’. The embraced number is the atomic context recursion level: 1 is the outer most.

Line 10:

After each emit command a list of rules to be called is printed.

Line 12:

“call rule” is printed when a rule is executed, followed by some informations about the rule. After a call rule an indented block of actions inside the rule is printed.

Line 13-14:

“touch” indicates the acces of a cell that binds the rule to the cell. (Here the cell start of the “read tutorial” task). The Line is followed by a traceback.

Line 19:

Inside _rule_end _rule_start is emitted.