Cells
Every cell has an address (B2) and, ideally, a label (balance). When a cell
changes, the cells that read it recompute in dependency order. Nothing else runs.
Kinds of cells
Section titled “Kinds of cells”| Kind | Holds | You write | Start a new cell with |
|---|---|---|---|
| Input | A value you change | A Python literal: 200, [1, 2, 3], "Jul" |
just type |
| Formula | A computed value | Python; the last expression is the value | = |
| Linked input | A computed value you can override | A formula | the cell type picker |
| Resource | A value that arrives later (HTTP, files, slow work) | Python with await |
~ |
| Effect | No value: does something | Statements (print, write a file, call a webhook) |
! |
| Markdown | Text, a heading or a note page | Markdown with {{ expression }} |
the cell type picker |
Formulas, resources and effects run as the body of a function: return works
anywhere, also to stop early.
if not rows: return Nonetotal = sum(row["amount"] for row in rows)total / len(rows)References
Section titled “References”| You write | Means |
|---|---|
balance |
the cell labelled balance on the same sheet. Prefer labels. |
A1 |
cell A1 on the same sheet |
Budget.rent, Budget.A1 |
a cell on the sheet Budget |
- Labels are Python identifiers, unique within their sheet. They read better than coordinates and survive moving cells.
- Renaming a label in the cell panel updates every cell, note and action that uses it.
- A local variable with the same name as a cell wins. Don’t name locals like cells or
like coordinates (
A1). - A cell that depends on itself shows
Circular dependency detected.
To insert references by clicking, turn on Pick cells (the pointer button next to the editor) and click cells in the grid.
Reusable code
Section titled “Reusable code”- Function cells: a formula that ends with
deforclassholds that function. Other cells call it by its label:tax(income). The graph shows who uses it. - Shared code (… menu → Shared code): one Python block run once for the whole workbook. Use it only for state that must survive recomputation, such as a history of readings. Prefer function cells and input cells for everything else.
- Environment variables (Workbook settings): configuration strings read as
env["REGION"]. They are saved in the file, so never put secrets there.
Available in every cell without importing: math, statistics, asyncio, np
(NumPy, when installed), env, artifact, every, at, and everything in shared
code. Add other imports under Workbook settings → Imports and packages under
Packages.
Linked inputs
Section titled “Linked inputs”A formula you can override by hand. price = base_price * 1.2 follows base_price
until a user types another price; it shows Overridden and keeps the manual value
until Reset to derived value, or until base_price changes again.
For more control, the optional Computation field receives source (the formula’s
result) and previous (the last value, or None). This keeps a selection while it
is still among the options:
previous.value if previous is not None and previous.value in source else source[0]Resources
Section titled “Resources”A resource runs async code without blocking the workbook and shows loading, resolved or error. Cells that read it update when it resolves.
response = await client.get(url)response.json()It reloads when a cell it mentions changes. A running load can be cancelled from the cell’s menu or with Ctrl/Cmd+.; the previous value is kept.
To control exactly when it reloads, choose Resource parameters → Explicit in the
cell panel. Put cell reads in Parameters and use params in the async code:
# Parameters: return None to stay idle{"url": request_url, "limit": limit} if enabled else None# Async sourceresponse = await client.get(params["url"])response.json()[: params["limit"]]Effects
Section titled “Effects”An effect runs when a cell it mentions changes: send an alert, write a file, log a result. Guard effects that do something irreversible with a checkbox input, or make them an action, which runs only when someone chooses to.
Effects can change inputs:
cells.counter.update(lambda counter: counter + 1)cells.approved.set(False)cells.Settings.status.set("ready") # another sheetcells.price.reset() # a linked input back to its formulaAn effect’s writes are applied together when it succeeds and discarded if it fails. For commands a user triggers on purpose, use actions instead.
Running on a timer
Section titled “Running on a timer”A formula that calls every or at ticks by itself. Its value is the time of the last
tick, and every cell that mentions it reruns on each tick.
every(30) # every 30 secondsevery(minutes=5)at("08:00", "17:30", days="mon-fri") # local timeevery(refresh_seconds, enabled=running) # interval and pause switch from inputsClocks tick while the workbook is open in the app or runs with --watch. Missed ticks
are not caught up. See the Scheduled pipeline example.
Sheets
Section titled “Sheets”A workbook can have several sheets (tabs under the grid; + adds one). Sheets share
one graph: Budget.rent reads a cell on another sheet.
- Right-click a tab to rename, move, delete or Duplicate it. A duplicate calculates from its own inputs, which makes scenarios easy. References to other sheets stay shared.
- Copy and paste cells with Ctrl/Cmd+C and Ctrl/Cmd+V, also between windows. Cut and paste moves cells; references follow.
When a value counts as changed
Section titled “When a value counts as changed”By default a cell counts as changed when it holds a different Python object. Change it
under Equality in the cell panel: Value and type, Always changed, or a custom
function that returns True to keep the old value:
lambda previous, current: abs(previous - current) < 0.01Inputs that hold Python objects
Section titled “Inputs that hold Python objects”An input can start from code, for example make_state() from a function cell. It runs
once; changing the function does not reset the input. Values written by effects,
actions or scripts stay real Python objects. Literal values are saved in the file;
other values are marked Runtime value and rebuilt from the starting code on reopen.
To keep collected data out of the file, untick Save runtime value in Python file for that input.
Good habits
Section titled “Good habits”- Label every cell you reference. One idea per cell.
- Lay out left to right: inputs, then calculations, then notes and charts. Use sheets for stages (Inputs, Model, Report).
- Put a comment above an input value to say what it is and its unit.
- Formulas only compute. Side effects go in effects or actions; slow work in resources.
- Don’t change a value you read from another cell (
items.append(...)); build a new one.