About

ipyflow is a next-generation Python kernel for Jupyter and other notebook
interfaces that tracks dataflow relationships between symbols and cells during
a given interactive session. It aims to help notebook users reason about state
and avoid gotchas from out-of-order execution by providing features like
execution suggestions and reactivity. Keep reading to learn how. :)

Quick Start

To install, run:

To run an ipyflow kernel in JupyterLab, select “Python 3 (ipyflow)” from the
list of available kernels in the Launcher tab. For classic Jupyter, similarly
select “Python 3 (ipyflow)” from the list of notebook types in the “New”
dropdown dialogue.

Similarly, you can switch to / from ipyflow from an existing notebook by
navigating to the “Change kernel” file menu item in either JupyterLab or
classic Jupyter:

Note: reactive execution features are not yet supported in classic Jupyter
notebooks, but we are working on it!

Features

ipyflow ships with a JupyterLab extension that provides the following
user-facing features.

Execution Suggestions

To keep the execution state consistent with the code in cells, rerun the
turquoise-highlighted cells, and avoid the red-highlighted cells:

A turquoise-highlighted input with red-highlighted output just means that the
output may be out-of-sync.

Reactivity

Do you trust me? Good. It’s time to free yourself of the burden of manual
re-execution. Use ctrl+shift+enter (on Mac, cmd+shift+enter also works) to
execute a cell and its (recursive) dependencies reactively:

You can also run the magic command %flow mode reactive in any cell to enable
reactivity as the default execution mode:

Disable by running %flow mode normal.

Syntax Extensions

Prefixing a symbol with $ in a load context will cause the referencing cell
to re-execute itself, whenever the aforementioned symbol is updated (regardless
of execution mode):

You can also use the $ syntax in store contexts, which triggers cells that
reference the corresponding symbol to re-execute, regardless of whether the
reference is similarly $-prefixed:

Finally, you can also prefix with $$ to trigger a cascading reactive update
to all dependencies in the chain, recursively:

Integration with ipywidgets

ipyflow‘s reactive execution engine, as well as its APIs (see “State API” below)
are fully compatible with ipywidgets, allowing cells to respond to slider changes,
button clicks, and other events:

This functionality can be paired with other extensions like
stickyland to build fully reactive
dashboards on top of JupyterLab + ipyflow.

State API

ipyflow must understand the underlying execution state at a deep level in
order to provide its features. It exposes an API for interacting with some of
this state, including a code function for obtaining the code necessary to
reconstruct some symbol:

# Cell 1
from ipyflow import code

# Cell 2
x = 0

# Cell 3
y = x + 1

# Cell 4
print(code(y))

# Output:
"""
# Cell 2
x = 0

# Cell 3
y = x + 1
"""

You can also see the cell (1-indexed) and statement (0-indexed) of when a
symbol was last updated with the timestamp function:

from ipyflow import timestamp
timestamp(y)
# Timestamp(cell_num=3, stmt_num=0)

To see dependencies and dependents of a particular symbol, use the deps and
users fuctions, respectively:

from ipyflow import lift

y_sym = lift(y)
y_sym.timestamp
# Timestamp(cell_num=3, stmt_num=0)

# Cell 1
from ipyflow import watchpoints

def watchpoint(obj, position, symbol_name):
    i