live_cells package

Module contents

class live_cells.Cell

Bases: object

Base cell class.

All cells should inherited this class.

add_observer(observer)

Add an observer to the cell.

observer is notified whenever the value of this cell changes.

Parameters:: observer – The observer to add to the cell.

error(all=False, type=None)

Create a cell that captures exceptions raised by this cell.

The returned cell evaluates to the last exception raised while computing the value of this cell..

If type is not None, the returned cell only captures exceptions which are of the type provided in type.

Parameters:

all – If True, the returned cell evaluates to None when this cell does not raise an exception. Defaults to False.
type – The type of exceptions to capture or None (default) to capture all exceptions.

Returns:

A new cell.

Return type:

Cell

Note

The value of the returned cell is None until an exception is raised while computing the value of this cell, regardless of the value of all.

logand(b)

Create a cell that computes the logical and of this cell and b.

Note

Cells returned by this method compare equal when called on the same object and the same arguments are provided.

Parameters:: b (Cell) – The operand cell.
Returns:: A cell which evaluates to the logical and of this cell’s value and the value of b.
Return type:: Cell

lognot()

Create a cell that computes the logical not of this cell.

Note

Cells returned by this method compare equal when called on the same object.

Returns:: A cell which evaluates to the logical not of the value of this cell.
Return type:: Cell

logor(b)

Create a cell that computes the logical or of this cell and b.

Note

Cells returned by this method compare equal when called on the same object and the same arguments are provided.

Parameters:: b (Cell) – The operand cell.
Returns:: A cell which evaluates to the logical or of this cell’s value and the value of b.
Return type:: Cell

on_error(other, type=None)

Create a cell that evaluates to another cell when this cell raises an exception.

When an exception is raised while computing the value of this cell, the returned cell evaluates to the value of other.

If type is not None, the returned cell evaluates to the value of other only when an exception of the same type as that provided in type is raised.

Parameters:

other (Cell) – The cell to evaluate to when this cell raises an exception.
type – Type of exceptions to handle or None (default) to handle all exceptions.

Returns:

A new cell.

Return type:

Cell

property peek

Read the value of this cell without reacting to changes.

This property returns a cell that has the same value as this cell but does not notify its observers when the value of this cell changes.

This should be used rather than accessing the Cell.value property directly to ensure that this cell is active.

remove_observer(observer)

Remove an observer from the cell.

After observer is removed, it is no longer notified when the value of the cell changes.

Note

To remove a given observer, this method has to be called the same number of times as add_observer was called for the same observer.

Parameters:: observer – The observer to remove.

select(if_true, if_false=None)

Create a new cell which selects between the values of two cells based on cond.

If the value of cond is True, the cell evaluates to the value of the if_true cell. If cond is False, the cell evaluates to the value of the if_false cell.

If if_false is None, the previous value of the cell is preserved when cond is False.

Parameters:

cond (Cell) – A condition cell evaluating to a boolean.
if_true (Cell) – Cell to evaluate to when cond is True.
if_false (Cell) – Cell to evaluate to when cond is False. If None (the default), the value of the returned cell is preserved when cond evaluates to False.

Returns:

A new cell.

Type:

Cell

property value: The value of the cell.

class live_cells.CellWatcher(callback, schedule=None)

Bases: object

Maintains the state of a cell watch function.

stop()

Stop the watch function from being called for future updates.

The watch callback will not be called again after this method is called.

exception live_cells.StopComputeException(default_value=None)

Bases: Exception

Exception used to indicate that the cell’s value should not be computed.

When this exception is raised inside the value computation function of a cell, the cell’s value is not updated. Instead the cell’s current value is preserved.

Parameters:: default_value – The value to initialize the cell to, if this exception is thrown while computing the initial value of the cell.

live_cells.batch()

Batch changes to mutable cells within a given managed context.

When this context manager is used, the observers of the mutable cells that are set within the with block managed by the context manager, are only notified when exiting the context.

This has no effect when used when a batching is already in effect before the context manager is created.

Example

with batch():
    a.value = 1
    b.value = 2

# Observers of `a` and `b` are only notified when
# exiting the `with` block.

live_cells.batched(fn)

Apply the batch context manager to the decorated function.

This decorator is equivalent to replacing wrapping a call to fn with the following:

with batch():
    fn()

Parameters:: fn (function) – A function
Returns:: A function that calls fn while applying cell batching.
Return type:: function

live_cells.computed(compute=None, key=None, changes_only=False)

Create a computed cell with dynamically determined arguments.

A computed cell with compute function compute is created. compute is a function of no arguments, that is called to compute the value of the cell. The cells referenced within compute, using the function call syntax, are automatically registered as dependencies of the cell such that when their values change the value of the computed cell is recomputed.

Note

This function may be used as a decorator by omitting the compute argument, in which case the decorated function is used as the compute function. The cell is then referenced using the name of the decorated function.

Parameters:

compute (function) – Function of no arguments called to compute the value of the cell.
key – Key identifying the cell if not None. Defaults to None.
changes_only – If True the cell only notifies its observers if its new value is not equal to its previous value. Defaults to False.

Returns:

A computed cell.

live_cells.mutable(value=None, key=None)

Create a mutable cell with an initial value.

The value of a mutable cell can be changed by setting its value property.

Parameters:

value – The initial value of the cell, defaults to None.
key – Key identifying the cell if not None, defaults to None.

Returns:

A mutable cell.

live_cells.none(default_value=None)

Stop the computation of a computed cell’s value.

When this method is called inside the value computation function of a computed cell, the cell’s value is not updated. Instead the cell’s current value is preserved.

If this function is called during the computation of the cell’s initial value, the cell’s initial value is set to default_value.

Parameters:: default_value – The value to assign to the cell if called during the computation of its initial value.
Raises:: StopComputeException – This exception is raised to signal to the enclosing computed cell to abort the computation.

live_cells.value(value)

Create a cell with a constant value.

The value of a constant cell never changes and its observers are never notified.

Note

Two constant cells compare equal if their values are equal.

Parameters:: value – The constant value of the cell.
Returns:: A constant cell.

live_cells.watch(callback=None, schedule=None)

Register a callback to run when the values of cells change.

callback (A function of no arguments) is called once immediately to determine the cells referenced within it. It is then called again whenever the values of the referenced cells change.

To stop callback from being called for further changes to the referenced cell values, call the CellWatcher.stop method on the CellWatcher object returned by this function.

Attention

Within callback, Cells should only be referenced using the function call syntax and never by referencing the value property directly.

Note

This function may be used as a decorator by omitting the callback argument, in which case the decorated function is used as the watch function. The watch function’s CellWatcher is then referenced using the name of the decorated function.

Parameters:

callback (function) – The watch function.
schedule (function, optional) – A function which is called with the callback function provided as an argument. When this function is called, it should schedule the callback function provided to it to be called.

Returns:

The handle to the watch function’s state.

Return type:

CellWatcher