XLSX: Python cells as _xlfn._xlws.PY() formulas, code in the Python part, cached values; opening limits

A Python cell is written to xlsx as [MS-XLSX] 2.3.10 specifies: its
formula is _xlfn._xlws.PY(i,0|1), where i is the zero-based index of the
cell's script in the workbook's Python part and 0|1 the return type, 0
for an Excel value and 1 for a Python object. The part (2.1.23) is
xl/python.xml, content type application/vnd.ms-excel.python+xml,
related from the workbook part with
http://schemas.microsoft.com/office/2023/09/relationships/Python; its
root python holds pythonScripts, one pythonScript per Python cell in the
order the cells are written, with the code in code. The code keeps its
xl() references as text, so the formula has no further arguments. The
cell keeps its cached value. A spilling result is written like a dynamic
array (cm="1", t="array" ref=...) with the spilled values cached, so
other applications show the values (and #NAME? if they recalculate).

The reader turns a PY( formula with or without the _xlfn. and _xlws.
prefixes into a Python cell. An index names a script of the Python part,
and each %Px% in the script becomes the text of the formula's argument x
(2.3.10.4). The string-literal form, PY("chunk"&"chunk",0|1), still
reads, from the formula's own text so line breaks in the code survive. A
formula naming a script the part doesn't hold keeps only its cached
value, with a warning: no calculation can evaluate it. The reader keeps
the cached spilled values as the cell's result, so a workbook from Excel
shows its arrays without running anything. Python errors are cached as
#VALUE!, as #SPILL! and #CALC! already are. Native JSON keeps Cell.py
whole: code, return type, the last result and the exact error.

Calc lays out a Python cell's kept result: Python cells are nodes of the
dependency graph that read nothing, and a pass takes a dirty Python
cell's result instead of evaluating it, so its array spills, is blocked
(#SPILL!) and unblocked, and feeds its dependents exactly like a
formula's. An array that is malformed or has more than 1,000,000 cells
(only a crafted file holds one) shows #SPILL!. A dirty Python cell is
pending in the pass, as a dirty formula is, so a formula, a range read
or a cell-by-cell range walk that reaches it before its turn lays it out
first rather than reading its old value.

Opening a file can't make the app loop over a claimed size: the reader
keeps a Python cell's spill range only when it has at most 1,000,000
cells (a range claiming the whole sheet is dropped with its values, as a
formula's spilled values are), and io::adopt_python rebuilds results for
at most 4,000,000 cells over the whole workbook, with a warning for the
cells it skips. The Python part is read up to 64 MB and 1,000,000
scripts, a script is kept up to one character past what a cell may
hold, and the cells take at most 64 MB of code from the part in all,
since several formulas can name one script. io::enforce_python_limits
drops the code of a cell whose code doesn't fit in 8,192 characters as
PY(...) (the cell keeps its cached value, with a warning) and a kept
result that isn't a well-formed array within the cap, each with its
spill range and spilled values, so the sheet and a save no longer show
the old spill. Formats that keep PY() as an ordinary formula (xls, xlsb,
ods) are adopted the same way. Opening a file runs nothing.

The command-sequence fuzzer sets Python cells (code with xl()
references, quotes, line breaks, and code at and over the size limit),
and its xlsx round-trip check allows the Python errors becoming
#VALUE!, which is what the file format stores.

Tests: the written formula naming its script, the Python part with its
content type and relationship, return types, a spilling table saved as a
dynamic array, Python errors as #VALUE!, the round trip of values, code,
long code with quotes and line breaks and the error, and no Python part
without Python cells; a workbook laid out as the format specifies (an
index, a parameter named as %P2%) read as Python cells with their
spilled values and saved back with its code in a Python part; the
string-literal form; a formula naming a missing script, with and without
a Python part; 20,000 cells naming one long script against the code
budget; the part's reader and writer (escaping, odd %P tokens, a long
script, a repeated parameter); a blocker in the spill area giving #SPILL!
and clearing it spilling again; the native JSON round trip; a spill
range claiming the whole sheet; the workbook-wide budget; hostile JSON
(code over the limit, a result claiming far more cells than it holds); a
malformed result that never spills; PY() formulas at 8,079 and 8,080
characters of code. Calc: formulas, MAX, SUM, COUNTA and SUMPRODUCT read
a dirty Python cell whose array is blocked before its turn, in a full
and an incremental recalculation, and see the array once it is
unblocked; enforce_python_limits removes the spill of dropped code and
of a dropped result, and keeps a sound one.
This commit is contained in:
prxnvt committed 2026-10-26 10:18:38 -04:00
1 parent c6c54c57e6
commit fcbbfa5142
13 files changed
+1133 -32

No files matched your search

+318
View File
@@ -0,0 +1,318 @@
//! The Python part ([MS-XLSX] 2.1.23, 2.3.10): where a workbook keeps the code of its Python cells.
//!
//! A Python cell's formula is `_xlfn._xlws.PY(index, return_type, …)` ([MS-XLSX] 2.3.10.2): the
//! first argument is the zero-based index of a `pythonScript` element in this part, whose `code`
//! is the cell's Python code, and the second is 0 (an Excel value) or 1 (a Python object). Further
//! arguments are references the code names as `%Px%`, `x` being the argument's zero-based index
//! ([MS-XLSX] 2.3.10.4). The part's root is `python` ([MS-XLSX] 2.4.102, CT_Python 2.6.249), with
//! `pythonScripts` (2.6.253) holding the `pythonScript` elements (2.6.252).
//!
//! GridCraft writes one script per Python cell, in the order the cells are written, with the code
//! as it is (its `xl()` references stay text in the code, so no further arguments). Reading
//! resolves the index and puts each `%Px%` back as the text of argument `x`. A formula that names
//! no script the part has keeps only its cached value. Hostile input is bounded: the part's size,
//! the number of scripts, each script's length, and the code all cells take from the part
//! together.
use gridcraft_formula::Expr;
use gridcraft_model::PyCode;
use gridcraft_model::python::{FILE_PREFIX, MAX_FORMULA_CHARS};
use crate::IoError;
use crate::read::Ctx;
use crate::xml::{self, El};
/// Namespace of the part.
pub const NS: &str = "http://schemas.microsoft.com/office/spreadsheetml/2023/python";
/// Relationship type from the workbook part.
pub const REL: &str = "http://schemas.microsoft.com/office/2023/09/relationships/Python";
/// Last segment of [`REL`], as [`crate::package::Rel::kind`] holds it.
const REL_KIND: &str = "Python";
/// Content type of the part.
pub const CONTENT_TYPE: &str = "application/vnd.ms-excel.python+xml";
/// Part name we write (the format names none; the relationship finds it).
pub const PART: &str = "xl/python.xml";
/// Largest Python part read.
const MAX_PART_BYTES: u64 = 64 * 1024 * 1024;
/// Most scripts read from the part.
const MAX_SCRIPTS: usize = 1_000_000;
/// Most characters kept of one script: one more than a cell's code may have, so a longer script
/// still fails [`PyCode::fits`] and its cell keeps only its value, with the usual warning.
const MAX_SCRIPT_CHARS: usize = MAX_FORMULA_CHARS + 1;
/// Most bytes of code all the cells of a workbook take from the part together. Several formulas
/// may name one script, so without it a small part could fill memory.
pub const MAX_CODE_BYTES: usize = 64 * 1024 * 1024;
/// The scripts read from a workbook's Python part, and what the cells took from them.
#[derive(Default)]
pub struct ScriptsIn {
scripts: Vec<String>,
/// Bytes of code the cells may still take ([`MAX_CODE_BYTES`] in all).
budget: usize,
/// Python cells that kept only their value: no such script, or over the budget.
missing: usize,
}
impl ScriptsIn {
/// The warning for the Python cells that kept only their value, if any.
pub fn warning(&self) -> Option<String> {
(self.missing > 0).then(|| {
format!(
"{} Python cell(s) name code the file's Python part doesn't hold (or holds too much of); they kept only their values",
self.missing
)
})
}
}
/// Reads the workbook's Python part, if it has one. A damaged part is a warning: its cells keep
/// their values.
pub fn read(cx: &mut Ctx<'_>, rels: &[crate::package::Rel]) -> Result<ScriptsIn, IoError> {
let mut out = ScriptsIn { budget: MAX_CODE_BYTES, ..ScriptsIn::default() };
let Some(rel) = rels.iter().find(|r| !r.external && r.kind.eq_ignore_ascii_case(REL_KIND)) else { return Ok(out) };
let bytes = match cx.pkg.read_limited(&rel.target, MAX_PART_BYTES) {
Ok(Some(b)) => b,
Ok(None) => {
cx.warn(format!("missing part {}", rel.target));
return Ok(out);
}
Err(IoError::TooLarge(m)) => {
cx.warn(format!("the Python part is too large ({m}); Python cells kept only their values"));
return Ok(out);
}
Err(e) => return Err(e),
};
let mut over = 0usize;
let parsed = xml::parse_streaming(&bytes, &["pythonScript"], &mut |el: El| {
if out.scripts.len() < MAX_SCRIPTS {
out.scripts.push(script_code(&el));
} else {
over += 1;
}
Ok(())
});
match parsed {
Ok(root) if root.name != "python" => {
cx.warn(format!("the Python part has the root <{}>; Python cells kept only their values", root.name));
out.scripts.clear();
}
Ok(_) => {}
Err(e) => cx.warn(format!("the Python part is damaged ({e}); kept {} scripts", out.scripts.len())),
}
if over > 0 {
cx.warn(format!("the Python part holds more than {MAX_SCRIPTS} scripts; {over} were not read"));
}
Ok(out)
}
/// A `pythonScript` element's code (ST_Xstring), with `\n` line breaks, cut after
/// [`MAX_SCRIPT_CHARS`] characters.
fn script_code(el: &El) -> String {
let text = el.child("code").map(|c| c.text.as_str()).unwrap_or_default();
let text = match text.char_indices().nth(MAX_SCRIPT_CHARS) {
Some((at, _)) => text.get(..at).unwrap_or_default(),
None => text,
};
gridcraft_model::python::normalize_code(&xml::decode_xstring(text))
}
/// `PY(index, 0|1, params…)`, as a file's formula holds it: the index, whether the return type is
/// a Python object, and the parameters. `None` for anything else (the code in a string literal
/// is [`PyCode::from_formula`]'s form).
fn py_call(expr: &Expr) -> Option<(usize, bool, &[Expr])> {
let Expr::Call(name, args) = expr else { return None };
let base = name.trim_start_matches("_XLFN.").trim_start_matches("_XLWS.");
if !base.eq_ignore_ascii_case("PY") {
return None;
}
let index = match args.first()? {
Expr::Number(n) if *n >= 0.0 && n.fract() == 0.0 && *n < MAX_SCRIPTS as f64 => *n as usize,
_ => return None,
};
let object = match args.get(1)? {
Expr::Number(n) if *n == 0.0 => false,
Expr::Number(n) if *n == 1.0 => true,
_ => return None,
};
Some((index, object, args.get(2..).unwrap_or_default()))
}
/// What a file formula is to Python.
#[derive(Debug, PartialEq)]
pub enum PyFormula {
/// Not a `PY(…)` call: an ordinary formula.
Not,
/// A Python cell with this code.
Code(PyCode),
/// A `PY(index, …)` call naming a script the part doesn't hold (or over the budget): the
/// cell keeps only its cached value, since no calculation can evaluate the formula.
Missing,
}
/// What a file formula makes: a Python cell from the Python part when it names a script, or from
/// string literals ([`PyCode::from_formula`]). `formula` is the parsed formula, `raw` the
/// formula's own text, which keeps line breaks in literal code.
pub fn cell_code(scripts: &mut ScriptsIn, formula: &gridcraft_model::Formula, raw: &str) -> PyFormula {
// The cheap test first: most formulas are not `PY(` calls.
if !gridcraft_model::python::is_py_formula(&formula.text) {
return PyFormula::Not;
}
let expr = formula.expr_arc();
let Some((index, object, params)) = expr.as_deref().and_then(py_call) else {
return PyCode::from_formula(raw).map_or(PyFormula::Not, PyFormula::Code);
};
let code = scripts.scripts.get(index).map(|code| with_params(code, params));
match code.filter(|c| c.len() <= scripts.budget) {
Some(code) => {
scripts.budget -= code.len();
PyFormula::Code(PyCode { object, ..PyCode::new(&code) })
}
None => {
scripts.missing += 1;
PyFormula::Missing
}
}
}
/// `code` with every `%Px%` (`x` at least 2, naming one of `params`) replaced by the parameter's
/// text. Stops growing past [`MAX_SCRIPT_CHARS`] characters: such code can't be a cell's.
fn with_params(code: &str, params: &[Expr]) -> String {
if params.is_empty() || !code.contains("%P") {
return code.to_string();
}
let texts: Vec<String> = params.iter().map(gridcraft_formula::print).collect();
let mut out = String::with_capacity(code.len());
let mut chars = 0usize;
let mut push = |out: &mut String, piece: &str| {
out.push_str(piece);
chars = chars.saturating_add(piece.chars().count());
chars > MAX_SCRIPT_CHARS
};
let mut rest = code;
while let Some(at) = rest.find("%P") {
if push(&mut out, rest.get(..at).unwrap_or_default()) {
return out;
}
let after = rest.get(at + 2..).unwrap_or_default();
let digits = after.bytes().take_while(u8::is_ascii_digit).count();
let param = (1..=6)
.contains(&digits)
.then(|| after.get(..digits).and_then(|d| d.parse::<usize>().ok()))
.flatten()
.filter(|_| after.as_bytes().get(digits) == Some(&b'%'))
.and_then(|x| x.checked_sub(2))
.and_then(|x| texts.get(x));
let full = match param {
Some(text) => {
rest = after.get(digits + 1..).unwrap_or_default();
push(&mut out, text)
}
None => {
rest = after;
push(&mut out, "%P")
}
};
if full {
return out;
}
}
out.push_str(rest);
out
}
/// The formula a Python cell is saved as: `_xlfn._xlws.PY(index,0|1)`, its code being script
/// `index` of the part ([`write`]).
pub fn file_formula(index: usize, object: bool) -> String {
format!("{FILE_PREFIX}PY({index},{})", u8::from(object))
}
/// The Python part holding `scripts`, in order. Only written when there is at least one: the
/// format requires one `pythonScript` in `pythonScripts`.
pub fn write(scripts: &[String]) -> String {
let mut xml = format!("{}<python xmlns=\"{NS}\"><pythonScripts>", crate::write::XML_DECL);
for code in scripts {
xml.push_str("<pythonScript><code>");
xml.push_str(&xml::esc(&xml::encode_xstring(code)));
xml.push_str("</code></pythonScript>");
}
xml.push_str("</pythonScripts></python>");
xml
}
#[cfg(test)]
mod tests {
use super::*;
fn formula(text: &str) -> gridcraft_model::Formula {
gridcraft_model::Formula::new(&crate::fmla::from_file(text))
}
fn scripts(list: &[&str]) -> ScriptsIn {
ScriptsIn { scripts: list.iter().map(|s| s.to_string()).collect(), budget: MAX_CODE_BYTES, missing: 0 }
}
#[test]
fn reads_the_index_form_and_parameters() {
let mut s = scripts(&["1 + 1", "df = xl(\"%P2%\", headers=True)\nxl('%P3%') + %P9% + %P1%"]);
let code = |s: &mut ScriptsIn, text: &str| match cell_code(s, &formula(text), text) {
PyFormula::Code(py) => Some(py),
_ => None,
};
let a = code(&mut s, "_xlfn._xlws.PY(0,1)").unwrap();
assert_eq!((a.code.as_str(), a.object), ("1 + 1", true));
let b = code(&mut s, "_xlfn._xlws.PY(1,0,A1:B3,Sheet2!$C$4)").unwrap();
assert_eq!(b.code, "df = xl(\"A1:B3\", headers=True)\nxl('Sheet2!$C$4') + %P9% + %P1%");
assert!(!b.object);
// The literal form still reads (other applications, older files).
assert_eq!(code(&mut s, "_xlfn._xlws.PY(\"x = 1\",0)").unwrap().code, "x = 1");
// A script the part doesn't hold: the cell keeps its value, and is counted for the warning.
let gone = "_xlfn._xlws.PY(7,0)";
assert_eq!(cell_code(&mut s, &formula(gone), gone), PyFormula::Missing);
assert!(s.warning().is_some());
for not in ["_xlfn._xlws.PY(-1,0)", "_xlfn._xlws.PY(0.5,0)", "_xlfn._xlws.PY(0,2)", "PY(A1,0)", "SUM(0,1)", "PYTHON_TYPE(A1)"] {
assert_eq!(cell_code(&mut s, &formula(not), not), PyFormula::Not, "{not}");
}
}
#[test]
fn hostile_scripts_are_bounded() {
// Many formulas naming one script take from one budget.
let code = "x".repeat(1_000);
let mut s = ScriptsIn { scripts: vec![code], budget: 2_500, missing: 0 };
let f = formula("_xlfn._xlws.PY(0,0)");
let taken = (0..5).filter(|_| matches!(cell_code(&mut s, &f, ""), PyFormula::Code(_))).count();
assert_eq!(taken, 2);
assert_eq!(s.missing, 3);
// A parameter repeated many times stops growing the code just past a cell's limit.
let many = "%P2%".repeat(5_000);
let out = with_params(&many, &[Expr::Name("A_VERY_LONG_NAME_FOR_A_RANGE".into())]);
assert!((MAX_SCRIPT_CHARS..MAX_SCRIPT_CHARS + 40).contains(&out.chars().count()), "{}", out.len());
assert!(!PyCode::new(&out).fits());
// Odd tokens stay as they are.
assert_eq!(with_params("%P%P2%%P99999999%%P", &[Expr::Number(1.0)]), "%P1%P99999999%%P");
// A long script is cut just past the limit, so it fails the cell's check.
let el = El {
name: "pythonScript".into(),
children: vec![El { name: "code".into(), text: "y".repeat(20_000), ..El::default() }],
..El::default()
};
assert_eq!(script_code(&el).chars().count(), MAX_SCRIPT_CHARS);
}
#[test]
fn written_scripts_read_back() {
let codes = vec!["a = 1\nb = \"two\" & 'three' <tag>".to_string(), "_x0041_ \u{1}".to_string(), String::new()];
let xml = write(&codes);
assert!(xml.contains(NS) && xml.contains("<pythonScripts><pythonScript><code>a = 1\nb = \"two\" &amp; 'three' &lt;tag&gt;</code>"), "{xml}");
let mut read = Vec::new();
let root = xml::parse_streaming(xml.as_bytes(), &["pythonScript"], &mut |el| {
read.push(script_code(&el));
Ok(())
})
.unwrap_or_default();
assert_eq!(root.name, "python");
assert_eq!(read, codes);
assert_eq!(file_formula(3, true), "_xlfn._xlws.PY(3,1)");
}
}