Engine: python.set makes a Python cell; this build stores code and

doesn't run it

python.set {cell?, code, output?: object|value} makes the cell (the
active cell by default) a Python cell, keeping its style and taking a
formula and its spill away. `output` is the return type Microsoft
documents for PY(): an Excel value (the default) or a Python object;
without it a Python cell keeps the one it had. The code must fit in
Excel's 8,192-character formula once written as PY(...), quotes doubled
and literals joined, so the command checks the encoded formula rather
than a character count. A table's header row refuses Python (it holds
the column's name, as Excel keeps formulas out of headers), and a locked
cell on a protected sheet refuses it through the usual protection check.

Nothing runs Python here. Unchanged code keeps its cached result and
value; new or changed code shows #BLOCKED!. One undo step takes the cell
back.

Sheet::clear_spill removes the spilled values inside a range with work
bounded by the values stored, not by the range's size.

In the interface, F2, a double click or the formula bar on a Python cell
edits its code, and a changed text is committed through python.set,
which keeps the return type; through cell.set it would have replaced the
Python cell with an ordinary cell holding the code as text. Typing over
a Python cell replaces it, as typing over a formula does, and committing
the code unchanged writes nothing. Deleting all the code clears the
cell through cell.set, as an empty entry clears any other cell; code
of spaces is still code.

Tests: the code and return type in cell.get, #BLOCKED! for new code,
cached results kept for unchanged code, the active-cell default, undo,
refused params (missing or non-text code, a bad cell, a bad return
type), the encoded limit at 8,079 and 8,080 characters and with doubled
quotes, a table header, a protected sheet, and a formula's spill taken
away. A UI test edits a Python cell's code with F2 and Enter, commits it
unchanged, and types over it; another clears a Python cell by deleting
all its code, keeps code of spaces, and undoes the clearing.

crates/engine/src/cmd/python.rs

@@ -0,0 +1,96 @@
+//! Python in cells: making and editing Python cells. This build stores the code and the last
+//! result a file cached; it doesn't run Python, so a cell with new or changed code shows
+//! `#BLOCKED!`.
+
+use std::sync::Arc;
+
+use gridcraft_core::{CellRef, Value};
+use gridcraft_model::{Cell, PyCode, python::MAX_FORMULA_CHARS};
+use serde_json::{Value as Json, json};
+
+use super::{CommandSpec, bad, cell_param_on, cmd, edit, has_doc, str_param, target_sheet};
+use crate::{EngineError, Result, Session};
+
+pub fn specs() -> Vec<CommandSpec> {
+    vec![cmd!(
+        "python.set",
+        "Set Python Code",
+        [],
+        None,
+        "{cell?, code, output?: object|value} makes the cell (default: the active cell) a Python cell with this code; the code must fit in Excel's 8,192-character formula once written as PY(…). `output` is the return type: `value` (an Excel value, the default) or `object` (a Python object)",
+        has_doc,
+        set
+    )]
+}
+
+fn target_cell(s: &Session, p: &Json) -> Result<(usize, CellRef)> {
+    let sheet = target_sheet(s, p)?;
+    let at = match cell_param_on(s, p, "cell", sheet)? {
+        Some(c) => c,
+        None => s.doc()?.selection.active,
+    };
+    Ok((sheet, at))
+}
+
+fn existing(s: &Session, sheet: usize, at: CellRef) -> Result<Option<PyCode>> {
+    Ok(s.doc()?.wb.sheet(sheet).and_then(|sh| sh.cell(at)).and_then(|c| c.py.as_deref()).cloned())
+}
+
+fn output_mode(p: &Json, key: &str) -> Result<Option<bool>> {
+    match str_param(p, key) {
+        None => Ok(None),
+        Some(m) if m.eq_ignore_ascii_case("object") => Ok(Some(true)),
+        Some(m) if m.eq_ignore_ascii_case("value") => Ok(Some(false)),
+        Some(m) => Err(bad("python.set", format!("`{key}` is `object` or `value`, not `{m}`"))),
+    }
+}
+
+fn set(s: &mut Session, p: &Json) -> Result<Json> {
+    let (sheet, at) = target_cell(s, p)?;
+    let code = match p.get("code") {
+        Some(Json::String(c)) => c.as_str(),
+        Some(_) => return Err(bad("python.set", "`code` must be text")),
+        None => return Err(bad("python.set", "missing `code`")),
+    };
+    let mode = output_mode(p, "output")?;
+    let old = existing(s, sheet, at)?;
+    let object = mode.or(old.as_ref().map(|o| o.object)).unwrap_or(false);
+    let mut py = PyCode { object, ..PyCode::new(code) };
+    if !py.fits() {
+        return Err(bad(
+            "python.set",
+            format!("the code doesn't fit in one cell: written as PY(…) it would be longer than Excel's {MAX_FORMULA_CHARS}-character formula limit"),
+        ));
+    }
+    // A table header is the column's name, never a formula or code (as in Excel).
+    let header =
+        s.doc()?.wb.sheet(sheet).is_some_and(|sh| sh.tables.iter().any(|t| t.header_row && t.range.start.row == at.row && t.range.contains(at)));
+    if header {
+        return Err(EngineError::Other(format!("{} is a table header; Python cells can't go in a table's header row", at.a1())));
+    }
+    // Unchanged code keeps its result (and its value); new code has none until it runs.
+    let keep = old.filter(|o| o.code == py.code);
+    let value = match &keep {
+        Some(o) => {
+            py.output = o.output.clone();
+            py.stale = o.stale;
+            None
+        }
+        None => Some(gridcraft_model::python::BLOCKED),
+    };
+    edit(s, |cx| {
+        let sh = cx.sheet_mut(sheet)?;
+        let style = sh.style_id(at);
+        let value = value.unwrap_or_else(|| sh.cell(at).map(|c| c.value.clone()).unwrap_or(Value::Empty));
+        // A formula's spill (or the old result's) goes with what the cell held.
+        if let Some(r) = sh.spill_ranges.remove(&at) {
+            sh.clear_spill(r);
+        }
+        sh.set_cell(at, Cell { value, formula: None, style, py: Some(Arc::new(py)) });
+        cx.touch(sheet, at);
+        Ok(())
+    })?;
+    let d = s.doc()?;
+    let shown = d.wb.sheet(sheet).map(|sh| sh.value(at)).unwrap_or_default();
+    Ok(json!({"cell": at.a1(), "value": crate::cmd::inspect::value_json(&shown)}))
+}