CellRune

CellRune is a Rust library for bounded XLSX/XLSM reading and deterministic formula calculation. It keeps the workbook read from disk immutable, returns recalculated values in a separate snapshot, and can retain an exact package backing for explicit round-trip writing.

Rust installation

The CellRune Rust crate 0.1.4 requires Rust 1.88 or newer.

cargo add cellrune@0.1.4

Or add the dependency directly:

[dependencies]
cellrune = "0.1.4"

Features

reads .xlsx files from paths, byte slices, or Read + Seek streams;
opens package-backed .xlsx and .xlsm documents with exact SHA-256 identity and bounded round-trip preservation;
preserves sheet order, sparse cells, formulas, saved results, defined names, and relevant number-format metadata;
expands shared formulas while preserving absolute and relative references;
returns typed formula values and stable per-cell calculation issues in one result snapshot;
reports normalized per-workbook function demand and exposes the implemented function catalog;
applies configurable limits to ZIP, XML, workbook, formula, dependency, text, and array work;
never executes macros, never follows external links, and never reads the host clock for TODAY() or NOW();
returns stable error and issue codes for programmatic handling;
materializes recalculated typed results into existing .xlsx/.xlsm packages with strict or explicit cache-invalidation policies;
creates canonical .xlsx workbooks and applies typed cell, formula, sheet, name, number-format, date-system, and calculation-property edits through WorkbookDraft;
reads, queries, preserves, and explicitly authors SpreadsheetML phonetic annotations and default frozen panes without mixing presentation state into formula calculation;
exposes the same versioned read/edit/calculate/write contract through typed Python and Node.js/TypeScript native packages;
supports atomic typed edit batches, persistent parsed/dependency state, safe incremental recalculation, bounded result deltas, cooperative cancellation, and stale-result rejection;
provides a local stdio MCP server with high-level open, inspect, edit, recalculate, range-read, delta, and verified Save As tools over the same interop session; and
raw-copies unchanged package entries without exposing ZIP or XML implementation types.

Usage

use cellrune::{
    CalculationCellResult, CalculationOptions, ReadOptions, calculate_workbook, read_xlsx_path,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let workbook = read_xlsx_path("input.xlsx", ReadOptions::default())?;
    let calculation = calculate_workbook(&workbook, CalculationOptions::default());

    for (cell, result) in calculation.cells() {
        match result {
            CalculationCellResult::Value(value) => println!("{cell:?}: {value:?}"),
            CalculationCellResult::Unavailable(issue) => {
                eprintln!("{cell:?}: {}", issue.code().as_str());
            }
        }
    }

    Ok(())
}

Reading and calculation are separate operations. calculate_workbook does not modify the source WorkbookSnapshot or its saved XLSX results. It attempts every formula in the workbook: successfully calculated cells contain a typed Value, while a cell that cannot be calculated contains a structured Unavailable(CalculationIssue). One unavailable formula does not suppress independent results; dependent formulas report BlockedByUpstream when applicable. Volatile functions require deterministic inputs through CalculationOptions: with_today_serial for TODAY() and with_now_serial for NOW(). Use with_arithmetic_semantics and with_financial_solver_semantics to opt into the raw IEEE-754 and extended-search behavior shipped through 0.1.2; the defaults select Excel-compatible cancellation and Microsoft's function-specific solver budgets. Use supported_function_catalog for the build's exact function surface and scan_function_usage to summarize the functions used by a workbook. scan_formula_capabilities remains available as an optional static inventory for migration planning and user-interface reporting; calculation does not require it. INDEX follows Excel's zero-index reference behavior: a zero row or column selects the complete corresponding column or row, and zero for both selects the complete input range. Scalar formulas apply legacy implicit intersection, while array formulas can materialize the selected rectangle.

For repeated programmatic edits, use WorkbookCalculationSession instead of rebuilding stateless calculation state after every cell:

use cellrune::{
    CalculationOptions, CancellationToken, CellAddress, CellValue, EditBatch, FiniteNumber,
    RecalculationMode, SheetId, WorkbookCalculationSession, WorkbookChange,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut session = WorkbookCalculationSession::create();
    let sheet = SheetId::new(1)?;
    let receipt = session.apply_changes(
        0,
        EditBatch::new([WorkbookChange::set_cell_value(
            sheet,
            CellAddress::from_a1("A1")?,
            CellValue::Number(FiniteNumber::new(42.0)?),
        )]),
    )?;
    let delta = session.recalculate(
        RecalculationMode::Auto,
        CalculationOptions::default(),
        CancellationToken::new(),
    )?;
    assert_eq!(delta.result_revision(), receipt.result_revision());

    Ok(())
}

Auto evaluates a proven dirty subset and falls back to the same full-workbook calculation semantics when formula, name, sheet, option, dynamic-reference, or spill topology is uncertain. Forced incremental mode fails closed instead of guessing. Sessions use optimistic semantic revisions for atomic edits, retain bounded result-delta history, and reject stale calculations. A batch whose accepted operations make no semantic change keeps the current revision, topology, and installed calculation instead of forcing a redundant recalculation. Long-running work can be prepared outside the session lock with prepare_recalculation, cancelled through a request-owned CancellationToken, and installed only if its source revision is still current.

open_xlsx_document_* retains the exact input package for writing. write_recalculated_xlsx_bytes, write_recalculated_xlsx, and write_recalculated_xlsx_path bind a calculation to that exact input, update typed formula caches, remove stale calculation chains, preserve unrelated package content, and reopen the output before reporting success. Strict mode rejects incomplete calculations without producing an artifact; cache invalidation is an explicit opt-in policy. write_preserved_xlsx_bytes remains available for an unchanged preservation copy.

WorkbookDraft::new creates a canonical workbook, while WorkbookDraft::from_document retains the source package for preservation-aware edits. Calculate the draft's current workbook() and pass both objects to write_xlsx_draft_bytes, write_xlsx_draft, or write_xlsx_draft_path. A mutation that changes workbook semantics advances the semantic revision, so a calculation made before the latest effective edit is rejected. An accepted no-op keeps the revision unchanged. Path writes are Save As operations and never replace an existing destination unless replacement is explicitly enabled. Canonical drafts can author dynamic-array formulas with WorkbookDraft::set_cell_dynamic_formula; calculation resolves their spill region, detects occupied targets, and materializes followers for writing. Existing document-backed dynamic formulas can be recalculated without changing their metadata, while adding or replacing one is rejected until source metadata-index merging is implemented.

Package-backed documents expose phonetic annotations and frozen panes through XlsxDocument::presentation(). WorkbookDraft provides atomic set_annotated_text, set_phonetics, clear_phonetics, set_frozen_pane, and clear_frozen_pane mutations. Phonetic base ranges are zero-based half-open UTF-16 code-unit ranges. Presentation-only changes have a separate revision and reuse an otherwise current calculation. Source rich-text phonetic editing, RTL pane authoring, and PHONETIC() calculation remain explicit unsupported boundaries.

Runnable examples are shipped in the crate package under examples/ and live at crates/cellrune/examples/ in this repository. From the repository root, run one with cargo run -p cellrune --example <name> -- [arguments]; from an extracted crate package, omit -p cellrune. See the public llms.txt reference for the complete example inventory and a condensed public API reference.

Language bindings

Python uses the mainstream PyO3 + maturin native-extension path. Node.js and TypeScript use napi-rs over stable Node-API with Promise-backed native work and exact-version platform packages. Neither binding requires a consumer Rust toolchain when installed from a wheel or prebuilt npm artifact.

The 0.1.4 release line targets Python 3.10 through 3.14 and Node.js 22 or newer. Install the bindings with:

python -m pip install "cellrune==0.1.4"
npm install "@cellrune/node@0.1.4"

The bindings expose the same versioned read, edit, calculate, and write contract. Native package availability remains platform-specific; package managers must select a wheel or exact-version npm platform package compatible with the current runtime.

Python workbooks are context managers:

from cellrune import Workbook

with Workbook.create() as workbook:
    workbook.set_number("Sheet1", "A1", 41.0)
    workbook.set_formula("Sheet1", "B1", "=A1+1")
    workbook.calculate()
    # 0.1.2-compatible calculation remains available when required:
    workbook.calculate(
        arithmetic_semantics="ieee_754",
        financial_solver_semantics="extended_search",
    )
    workbook.save("output.xlsx")

In a Node.js ES module, close the workbook in finally:

import { Workbook } from "@cellrune/node";

const workbook = Workbook.create();
try {
  workbook.setNumber("Sheet1", "A1", 41);
  workbook.setFormula("Sheet1", "B1", "=A1+1");
  await workbook.calculate();
  await workbook.calculate({
    arithmeticSemantics: "ieee_754",
    financialSolverSemantics: "extended_search",
  });
  await workbook.save("output.xlsx");
} finally {
  workbook.close();
}

Python and Node.js close() calls are idempotent. Once close() returns, the binding-owned native session has been released. An active calculation is cooperatively cancelled, and subsequent operations fail with the stable interop.session.closed code.

Local MCP

cellrune-mcp is a local stdio-only MCP 2025-11-25 server for AI hosts. It exposes a finite set of high-level workbook workflow tools; spreadsheet functions remain formulas inside the workbook and are not registered one by one as MCP tools. Start it with one or more explicit filesystem roots:

cargo run --locked -p cellrune-mcp -- \
  --root /absolute/path/to/approved/workbooks

Its 11 tools are workbook_create, workbook_open, workbook_close, workbook_summary, workbook_read_range, workbook_function_usage, workbook_scan_capabilities, workbook_apply_changes, workbook_recalculate, workbook_changes_since, and workbook_save_as.

The server also publishes read-only JSON resources at cellrune://support/functions and the cellrune://sessions/{session_id}/summary resource template. Operators can set --max-sessions, --session-ttl-seconds, --max-response-bytes, --max-workbook-bytes, and --log-level; run cellrune-mcp --help for their defaults. Values outside the server's compiled policy limits are rejected at startup.

cellrune-mcp is not published to a package registry. Prebuilt bundles for Linux, macOS, and Windows are attached to each GitHub release, alongside their license materials and build provenance.

An MCP client can launch a release binary with configuration equivalent to:

{
  "mcpServers": {
    "cellrune": {
      "command": "/absolute/path/to/cellrune-mcp",
      "args": ["--root", "/absolute/path/to/approved/workbooks"]
    }
  }
}

The server canonicalizes configured roots at startup. Every workbook path supplied to a tool must be absolute and resolve inside one of those roots. The server bounds workbook/session/response resources, writes protocol traffic only to stdout, writes diagnostics only to stderr, and never provides a remote transport. Inputs are opened through an approved-root capability and read from the same file handle under the configured archive-byte ceiling. Existing destinations are protected unless the server starts with --allow-overwrite and a request also sets replace_existing. Save As retains an open destination-directory capability from validation through atomic installation, so renaming or replacing the ambient parent path cannot redirect a write outside the approved root. Resource lists use byte-bounded cursor pagination. At session capacity, create/open may evict the least-recently-used idle session; active sessions are never evicted. Give the server the narrowest practical root; another process with write access inside that root can still change workbook inputs and contents.

Tool results carry untrusted content. Cell text, sheet names, and defined names come from the workbook and are returned verbatim, so a crafted workbook can place text that reads as an instruction into a tool result. That is the same trust boundary as any other document a model reads: the server does not rewrite workbook content, and the consuming application is responsible for treating tool output as data rather than as instructions.

To inspect the local server before client integration:

npx --yes @modelcontextprotocol/inspector@1.0.0 \
  cargo run --locked -p cellrune-mcp -- \
  --root /absolute/path/to/approved/workbooks

Scope

CellRune supports ordinary Transitional SpreadsheetML workbooks and a scoped set of Excel formula syntax and functions. Unsupported formulas are returned as explicit per-cell calculation issues; other formulas continue to calculate.

The following are outside the current scope:

.xls, .xlsb, .ods, and CSV;
macro, add-in, external-workbook, query, or data-connection execution;
table structured references and 3-D references;
spill postfix references such as A1#, general LAMBDA, and data-table calculation; and
iterative calculation and automatic host-time inputs.

docs/NUMERICS.md records where calculated values differ from Excel and why, and documents the two calculation options added in 0.1.3: ArithmeticSemantics and FinancialSolverSemantics, which default to Excel's behavior and can be set to Ieee754 and ExtendedSearch for what 0.1.2 did.

Verification

The conformance/ tree carries the binary workbooks Excel actually calculated, together with their hashes, host metadata, and reviewed expectations. They are audited explicitly during local development:

cargo run \
  --package cellrune-integration-tests \
  --bin check_excel_oracle \
  --locked

This audit is deliberately separate from cargo test, CI, and publication. It covers 1,295 formula cells from Apache POI's FormulaEvalTestData, 266 materialized array results from its matrix fixture, and 661 selected results from the CellRune-authored formula oracle. Every selected case is classified; missing or extra classifications fail locally. The older POI formula cache currently has 1,290 matches and 5 documented divergences, enforced in both directions.

Two additional corpus tests are compiled but marked #[ignore] because their third-party inputs are not distributed in this repository. A developer who has supplied those inputs can run them explicitly:

WORKBOOK_FORMULA_CORPUS=/path/to/formulas.xlsx \
  cargo test -p cellrune-integration-tests --test external_formula_corpus -- --ignored

CELLRUNE_WORKBOOK_CORPUS=/path/to/workbook-or-directory \
  cargo test -p cellrune-integration-tests --test external_workbook_corpus -- --ignored

#[ignore] keeps a test registered and compilable while excluding it from ordinary cargo test; cloning the repository does not provide either external corpus.

License

CellRune is dual-licensed under either the MIT License or the Apache License, Version 2.0, at your option. You need to comply with only one of them, not both. Apache-2.0 includes an explicit patent grant; MIT does not. Both license texts are included in the source distribution.

Versions 0.1.0 through 0.1.2 were published under the MIT License alone and remain available under those terms. The dual license applies from version 0.1.3 onward. Dependency license information is provided in THIRD_PARTY_LICENSES.md.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cellrune-0.1.4.tar.gz (412.1 kB view details)

Uploaded Jul 27, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

cellrune-0.1.4-cp314-cp314-win_amd64.whl (1.6 MB view details)

Uploaded Jul 27, 2026 CPython 3.14Windows x86-64

cellrune-0.1.4-cp314-cp314-manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded Jul 27, 2026 CPython 3.14manylinux: glibc 2.28+ x86-64

cellrune-0.1.4-cp314-cp314-macosx_11_0_arm64.whl (1.5 MB view details)

Uploaded Jul 27, 2026 CPython 3.14macOS 11.0+ ARM64

cellrune-0.1.4-cp313-cp313-win_amd64.whl (1.6 MB view details)

Uploaded Jul 27, 2026 CPython 3.13Windows x86-64

cellrune-0.1.4-cp313-cp313-manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded Jul 27, 2026 CPython 3.13manylinux: glibc 2.28+ x86-64

cellrune-0.1.4-cp313-cp313-macosx_11_0_arm64.whl (1.5 MB view details)

Uploaded Jul 27, 2026 CPython 3.13macOS 11.0+ ARM64

cellrune-0.1.4-cp312-cp312-win_amd64.whl (1.6 MB view details)

Uploaded Jul 27, 2026 CPython 3.12Windows x86-64

cellrune-0.1.4-cp312-cp312-manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded Jul 27, 2026 CPython 3.12manylinux: glibc 2.28+ x86-64

cellrune-0.1.4-cp312-cp312-macosx_11_0_arm64.whl (1.5 MB view details)

Uploaded Jul 27, 2026 CPython 3.12macOS 11.0+ ARM64

cellrune-0.1.4-cp311-cp311-win_amd64.whl (1.6 MB view details)

Uploaded Jul 27, 2026 CPython 3.11Windows x86-64

cellrune-0.1.4-cp311-cp311-manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded Jul 27, 2026 CPython 3.11manylinux: glibc 2.28+ x86-64

cellrune-0.1.4-cp311-cp311-macosx_11_0_arm64.whl (1.5 MB view details)

Uploaded Jul 27, 2026 CPython 3.11macOS 11.0+ ARM64

cellrune-0.1.4-cp310-cp310-win_amd64.whl (1.6 MB view details)

Uploaded Jul 27, 2026 CPython 3.10Windows x86-64

cellrune-0.1.4-cp310-cp310-manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded Jul 27, 2026 CPython 3.10manylinux: glibc 2.28+ x86-64

cellrune-0.1.4-cp310-cp310-macosx_11_0_arm64.whl (1.5 MB view details)

Uploaded Jul 27, 2026 CPython 3.10macOS 11.0+ ARM64

File details

Details for the file cellrune-0.1.4.tar.gz.

File metadata

Download URL: cellrune-0.1.4.tar.gz
Upload date: Jul 27, 2026
Size: 412.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for cellrune-0.1.4.tar.gz
Algorithm	Hash digest
SHA256	`2bd623a6953c2b9f398790ed7e8640fbe9fc10c6d8ac3663211703a69759ce81`
MD5	`003d288a7ff2d8031a5e69c269c05f4e`
BLAKE2b-256	`e917f165dbd5f1071a6d315fa14fc9e75daa6b888036253163fc1ea99b17e10e`

Algorithm	Hash digest
SHA256	`37835799f400feef1d32c4bc48f6d5fcdafdd7fbb9b950dfe90166e973357b6f`
MD5	`12ebdd6c9e6e894f38a50a3f2338f0b4`
BLAKE2b-256	`63a93f77ee36ec6439cc11cc48b6d4e374b6db2d225bbbb0223430e7dbfcd8f7`

Algorithm	Hash digest
SHA256	`4230844d31b00b0e6c24264c7db9f4ea331e6c7203643d970c884ce6088ce32c`
MD5	`12fde906a306b71641059aa3f66194f5`
BLAKE2b-256	`20fe62eb7a2ed6640047d0d9f8e3fdc7e6aecea67761376d8b659e7474e34bfb`

Algorithm	Hash digest
SHA256	`65c4e46409832ce2d26ac4a145a6f932c3aee42c7a6331341ed38f49ec809297`
MD5	`1d5ad63077202787405d61bbc199d641`
BLAKE2b-256	`5e56af61984284cc643de8ca6178356327d3f845655ae59a29048eb06519107b`

Algorithm	Hash digest
SHA256	`602572667821539817323c3cbc40b229970c82b5367a44c026798dfd22382451`
MD5	`a15937f894b1667ff18c8a191a61dd95`
BLAKE2b-256	`e30a85d0e3e201604fa35a45b3ead8e84c9eaf4a30fbfd1a8d0f2236dd1ace00`

Algorithm	Hash digest
SHA256	`2fd955e68e5355dcb359c3234de3bd080e9b9ec54ba6054624e18d2891f42769`
MD5	`9fb4317ecabb60c6272859b50b3b9187`
BLAKE2b-256	`8a4778533fbbe88d554ecbd2cb5b8a7348c52ade975ab6b920c6c04144c04e41`

Algorithm	Hash digest
SHA256	`3409559f3b726e835045a3996109744e635c55267b68e06e4ee0286515e97bb7`
MD5	`a57fda1af402fc4bc4b343b4fc215d41`
BLAKE2b-256	`d481e416f1d382b2dac5a81825e5c2df5e9e10ca064cfcf504447703fd7a2c6a`

Algorithm	Hash digest
SHA256	`9eab1db1fd7e42e541e2c033cc632bc039f826545fbfb4ac8da8122b1941eebe`
MD5	`c8dda5c9887a674daeb064c842369df8`
BLAKE2b-256	`e9c6d0faadc63da58acce927ae72b976807de3afa881cd9f69b0d9d242779852`

Algorithm	Hash digest
SHA256	`4a3d6f0f350bb14e95e7577e154089d7d71e24f98719acb6ba6f829cd2d9b56d`
MD5	`66645d0a999710668a1dbb64ec8b30ab`
BLAKE2b-256	`129059878c443012305973df1d3f6cfd7cd724e95dc622cd74ded47352f15380`

Algorithm	Hash digest
SHA256	`3d31fc0c7288265aa05f7fe51f62e641db6225cc2c73e69a6275bd245f459126`
MD5	`c4c05a1cb34acffaab106e269fd25b28`
BLAKE2b-256	`33b8f07aa77e4261ba53e337e5fdd7de28c54c16bbfa40f97185569aed661c66`

Algorithm	Hash digest
SHA256	`f28cd6eb8d63637832677192e327885337e94bc295d4e53726f157c5e37f12bb`
MD5	`9598e7dcd72585e6a6dcced19975602c`
BLAKE2b-256	`8d9d9d3077fa9d4a7a14714b5391c696eee4f4763cfaf41371274ef5e6d5fee1`

Algorithm	Hash digest
SHA256	`74936cc6e53401907b0037ff8eeafdf80b38d794946acef0692eafc9c175dc34`
MD5	`436ef24204d9018e90f896c24a3cc4e9`
BLAKE2b-256	`6c20f1a165668f2c50c84e1a50fce7382be1d34ab35fb818e31a9c38a6825b6e`

Algorithm	Hash digest
SHA256	`3f78a6415d87f64bf197c42532296410731227727a94fbca2c808f07219ce93e`
MD5	`9315538702ab472b0b40edbd99f3937f`
BLAKE2b-256	`0e05ab49b897ffc3b87286c5fe36b6ada630ef950cfe4ce38c7d599081201bea`

Algorithm	Hash digest
SHA256	`b16bffa726b8dd71ebbd33551565ae63643c97171aa1286fd80004850056caa4`
MD5	`2316c71b99e338c29e4646145ec6bc01`
BLAKE2b-256	`235c07e6812587114079cb7e7622e1237c5d7ae433a3bd67c865ac147ac4ce9f`

Algorithm	Hash digest
SHA256	`583ff3d1c260d8e122c085e7be86df805d396278c02e9f64454558c8d6ef062f`
MD5	`d06406b4c8fb9777822c08fbd1baf278`
BLAKE2b-256	`a6bd977a28375c302b2e2706760cfa35914bfb54a81fe39a2201d2ba866e811f`

Algorithm	Hash digest
SHA256	`52ae0ad29444870b1f1b824959e1c327ae69562f2bde4cdc6c91cac160ac9a88`
MD5	`e6a0c30e924f8e36334f696ef92b00bb`
BLAKE2b-256	`8d1c8b29a6414cc08d990963ed29e6a33b511ec07975a7a002426012c47dbcf7`

cellrune 0.1.4

CellRune

Rust installation

Features

Usage

Language bindings

Local MCP

Scope

Verification

License

Contribution

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License expression

Requires

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata