Scripting API reference

This is the same document you'll find inside Spredin under Help.

The single, stable contract for driving Spredin by code instead of by clicking the UI. An LLM (local or cloud) reads this as context and writes Python against the global sheet; the spreadsheet is both the data source and the canvas.

The exact same text is injected into the AI's system prompt and shown in the in-app help, and a test asserts every method here exists in the runtime — so this never drifts and the model is never told about a method that doesn't exist.

Model#

Think in normal Python + pandas. numpy / pandas / scipy are installed but not imported for you — write import pandas as pd yourself (using pd without it is a NameError). sheet is the active sheet — already defined; never reassign it. Write top-level code (no def main(), no if __name__).

Row numbering — three systems, don't mix them#

This is the single most common way a script goes wrong (an IndexError, or a formula written into the header row):

for r in range(1, sheet.rows):            # data rows, 0-indexed
    sheet.set(r, 3, '=B%d+C%d' % (r+1, r+1))   # A1 rows are r+1
    same_row_in_df = df.iloc[r - 1]        # df has no header row

Never index a DataFrame with a sheet row number — that is off by one and runs off the end.

Methods#

Read / write (pandas-first)#

Cells#

Spredin ops (call the app engine — no pure-Python equivalent)#

Structure (whole rows / columns — 0-indexed; formulas rebase)#

Data tools (Data menu)#

Import / export (in-memory — no file dialog)#

Saving files is a menu action (File → Save / Export). Inside a script, read() gives you the data and to_csv / to_json hand it back out as text — an agent can persist or transmit that however it likes.

Reading another workbook — await open_file(path)

Opens a .sprd, .xlsx, .xls, .csv or .tsv from disk as data, without a window and read-only. Note the await.

The first time a script names a file you have not opened yourself in this session, Spredin asks you, showing the full path, before it reads it — Spredin opens only files you choose. Refusing raises an error in the script. A file you opened with File → Open or from the Finder is not asked about again.

wb = await open_file('/Users/me/Reports/jan.xlsx')
print(wb.sheets)                          # ['Summary', 'Raw']
total = wb.sheet('Summary').cell('B12')   # computed value, like sheet.value
rows = wb.sheet('Raw').read_values()      # every cell as a 2-D list
df = wb.sheet('Raw').read()               # a DataFrame, row 1 as the header
wb.close()

Formulas in the file compute against that file's own sheets and defined names. A CSV is converted the way File → Open converts it ($1,200 → 1200, dates → dates). A large .xlsx is read in full, so it can take a few seconds.

Gotchas worth knowing:

• filter treats row 1 of the range as data. Pass the range below the header (e.g. filter('A2:J5001', …)), or the header row will be tested and hidden too.
• write_col / write_row take a 0-based integer index, a column letter (write_col('E', …)), or a start cell (write_col('E2', …) / write_row('B6', …)).
• New sheets and named ranges become visible only after the script finishes. Sheets you create with add_sheet / pivot are fully writable within the run (write to the returned handle), but a formula that references a brand-new define_name (=SUM(NewName)) won't resolve until the run commits — do the name-based math in a later run, or compute it in Python.

Sheets#

Writing a script you can run twice#

Scripts are not idempotent by default: add_sheet('Report') on a second run returns a differently named sheet, and charts are append-only, so re-running stacks a new chart card on the old one. Two arguments fix both:

out = sheet.add_sheet('Report', replace=True)   # reuse + empty, don't pile up
out.clear_charts()                              # drop last run's charts first
out.write(rows, 'A1')
out.chart('A1:B10', 'bar', 'Revenue')

| sheet.copy_to(dest[, range][, at='A1']) | Copy this sheet's data (or a range) into another sheet handle. | | sheet.book(name) | Get an existing sheet by name. | | sheet.names() | List all sheet names. | | sheet.name | This sheet's name. |

Cross-sheet (combine multiple sheets)#

Every handle from sheet.book(name) / sheet.add_sheet(name) supports the same methods (read/write/value/set/chart/style/…), each acting on its own sheet — so a script can read several sheets and write results to another:

import pandas as pd
a = sheet.book('Sales').read()
b = sheet.book('Targets').read()
merged = a.merge(b, on='Region')
out = sheet.add_sheet('Combined')
out.write(merged)

Formulas can reference other sheets directly too: sheet.set('B2', "=Sales!B2-Targets!B2").

Number formats (number_format=)#

The vocabulary is Excel-ish except for dates, which use keywords. An unrecognised code is written into the cell verbatim — so number_format='yyyy-mm-dd' silently displays the literal text yyyy-mm-dd instead of a date. This block is injected into the LLM prompt for the same reason.

Dates from a script#

Write datetime.date / datetime.datetime objects, pandas Timestamps, numpy datetime64 values or ISO text ('2024-01-15', '2024-01-15T14:30:00') and the cell becomes a real date — a serial with the 'date' (or 'datetime') format already applied, so =F2+30, sorting and charts work. That is what Excel's VBA does on write. A locale form such as '1/2/2024' is not guessed at and stays text, and a cell that already has a date format keeps it. Reading a date cell back (sheet.value, sheet.read) gives the serial; pd.to_datetime(serial, unit='D', origin='1899-12-30') turns it into a Timestamp.

Formatting never changes the stored value, only its display.

Formula functions (inside "=…" strings)#

sheet.set(r, c, '=…') writes a live formula that the engine recalculates. The engine implements a specific set of Excel functions — anything outside it evaluates to #NAME?. The catalogue is generated from the engine itself, so it cannot drift out of date, and the full list with signatures is injected into the LLM prompt automatically. Adding a function without documenting it fails the build, so what the model is told is always what the engine actually has.

Covered, by family: math/trig (SUM ROUND ABS LN LOG EXP PI SIN…), stats (AVERAGE MEDIAN STDEV PERCENTILE NORM.DIST RANK…), lookup (XLOOKUP VLOOKUP INDEX MATCH INDIRECT OFFSET-free), logical (IF IFS IFERROR AND OR SWITCH), text (LEFT MID TEXTJOIN TEXTBEFORE SUBSTITUTE TEXT), date/time (TODAY EOMONTH NETWORKDAYS YEARFRAC WEEKNUM), finance (NPV IRR XIRR PMT IPMT SLN DDB), engineering (DEC2BIN BITAND…) and info (ISNA ISTEXT ERROR.TYPE). Browse them in-app by typing = in a cell.

Volatile caveat: RAND / RANDBETWEEN / NOW / TODAY compute once and cache (dependency-aware recalc has nothing to invalidate them on). Re-edit the cell to reroll.

Patterns#

# Analyze
df = sheet.read()
sheet.write(df.describe(), 'H1')

# Derived formula column (live, recalculates)
for r in range(1, sheet.rows):
    sheet.set(r, sheet.cols, '=B%d*C%d' % (r + 1, r + 1))

# Chart
sheet.chart('A1:C13', 'bar', 'Revenue by region')

# Copy a sheet (two lines, no loop)
dst = sheet.add_sheet('Copy')
dst.write(sheet.read())

# Restructure + tidy
sheet.insert_cols(2)                       # new blank column C
sheet.set(0, 2, 'Margin')
sheet.filter('A1:F100', 5, '>', 1000)      # hide rows where col F <= 1000
sheet.remove_duplicates('A2:F100')
sheet.freeze(1)                            # pin the header row

# Pivot to a new sheet by header NAME, then chart it
pv = sheet.pivot('A1:E5', rows=['Region'], values=[('Q1', 'sum'), ('Q2', 'sum')])
pv.chart('A1:C6', 'bar', 'Q1 vs Q2 by region')
# Re-edit the pivot in place (Excel field-pane edit, from code):
pv.update_pivot(rows=['Region'], values=[('Q1', 'sum')], cols='Region', show_as='pctOfTotal')
pv.refresh_pivot()                          # recompute if the source data changed

# Validation + named range
sheet.validate('B2:B100', 'list', options='Low,Medium,High')
sheet.define_name('Revenue', 'C2:C100')
sheet.set('E1', '=SUM(Revenue)')

# Hand data back out as text (no file dialog)
print(sheet.to_csv('A1:C10'))

Rules (for correct, hallucination-free output)#

• Call only the methods above — anything else raises a clear "no such method".
• sheet.write(...) places a whole table at once; sheet.set(r, c, v) is for a single cell only. Never loop to write a DataFrame.
• Don't import the app; don't reassign sheet.
• Chart with sheet.chart(...), never matplotlib / df.plot().

Agent control API — window.spredin (paste & run code into the panel)#

The sheet API above is what runs inside a Python script. To let an external agent/LLM put code into the lower Python panel and run it (no UI clicking), the app also exposes a small SDK on window.spredin (browser + Tauri webview):

window.spredin.version          // workbook/format version (number)

window.spredin.script.show()           // open the Python panel
window.spredin.script.hide()           // close it
window.spredin.script.get()            // current code in the active file (string | null)
window.spredin.script.set(code)        // replace the active file's code (async; opens panel)
window.spredin.script.append(code)     // append to the active file (async; opens panel)
window.spredin.script.run(code?)       // run; if `code` given, set it first.
                                      //   → Promise<{ ok, error?, output }>
window.spredin.script.output()         // captured stdout from the last run (string)
window.spredin.script.files()          // file names (string[])
window.spredin.script.activeFile()     // active file name (string | null)
window.spredin.script.newFile(name?, code?) // create+select a file → its name (async)
window.spredin.script.select(name)     // select a file by name → found? (async)

Mutating calls (set/append/run/newFile/select) auto-open the panel and wait for it to mount, so they work even if the panel is hidden. The Python you paste uses the sheet API documented above. Example:

const r = await window.spredin.script.run(`
import pandas as pd
df = sheet.read()
sheet.write(df.describe())
`);
console.log(r.ok, r.output);

Everything below is also what the AI writes against; there is no second, lesser API for automation.

Roadmap (planned additions — not yet available)#

These are planned; they are not callable yet and must not be used until shipped: sheet.sql(query) (DuckDB over a DataTable), sheet.db(url, query) (read-only connector → DataFrame). (sheet.sort, sheet.freeze, sheet.cond_format, sheet.pivot, filter, remove_duplicates, validate, define_name and the structure / import-export methods HAVE shipped — see the tables above.)