rea
Reverse engineer anything with agents, from app behavior down to native binaries.
- 470k
- TypeScript
- MIT
- 2 h ago
Zero-dependency, offline, deterministic spreadsheet formula engine for CSV worksheets
Repo gitstq/GridFormula, read from GitHub 1 min ago. gitstq has not joined Take My Repo.
gitstq/GridFormula is a public repo on GitHub by gitstq. Zero-dependency, offline, deterministic spreadsheet formula engine for CSV worksheets. It declares the MIT license on GitHub. It is written mainly in Python, has 0 stars and last changed on 2026-11-15. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-20.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
零依赖 · 离线 · 确定性 的电子表格公式求值引擎 —— 把 CSV 当作工作表,一条命令算出整张表。
🌐 选择语言 / 切換語言 / Choose language: 简体中文 · 繁體中文 · English
GridFormula 是一个用纯 Python 标准库写成的电子表格公式解析与求值引擎。它把一份普通的 CSV 文件当作工作表:以 = 开头的单元格是公式,其余是数字、布尔值或文本;执行一条命令,就能得到整张表的计算结果。
它解决的是一类很具体但反复出现的痛点:
| 痛点 | 现状 | GridFormula 的做法 |
|---|---|---|
| 📦 表格引擎太重 | Office SDK 功能强,但依赖多、体积大,塞不进 CI 或离线脚本 | 0 个第三方依赖,单目录即可运行 |
| 🔁 结果不可复现 | RAND / NOW 等易失函数让同一份表每次算出不同结果 |
只提供确定性纯函数,同输入逐字节可复现 |
| 🕳️ 错误难定位 | 一个 #VALUE! 传遍全表,却不知道源头在哪 |
完整错误值模型 + 求值轨迹显示依赖链与计算顺序 |
| 🔄 循环引用卡死 | 朴素递归实现遇到 A1=B1+1; B1=A1+1 会栈溢出 |
深度优先检测环,确定性地收敛为 #CIRCLE! |
| 🐼 为了算一列引入 pandas | 只想按列求和,却要装几百 MB 依赖 | CSV 即工作表,=SUM(B2:B9) 直接写进单元格 |
自研差异化亮点:零依赖纯标准库、刻意不实现易失函数以保证确定性、错误值沿依赖链传播、13 条静态体检规则、可审计求值轨迹、四种输出格式、CI 原生退出码,以及用标准库直接产出逐字节可复现的 wheel / sdist。
💡 灵感来源:GitHub Trending 上的
dream-num/univer(Office SDK)、we-promise/sure(个人理财)与louislam/uptime-kuma(自托管监控)共同指向的「轻量、内嵌、可复现的表格计算」需求。 ⚖️ 仅参考产品逻辑与所解决的痛点,代码 100% 独立自研,未复制任何第三方实现。
& 连接、% 百分比、^ 幂(右结合)、括号、A1:C9 区域、$A$1 绝对引用SUMIF、COUNTIF、VLOOKUP、IFERROR#CIRCLE!#DIV/0! #VALUE! #REF! #NAME? #NUM! #N/A #PARSE! #CIRCLE!,沿链传播且可被 IFERROR 拦截trace 子命令输出每个公式单元格的依赖列表与计算顺序,排查问题一目了然text / json / markdown / csv,所有子命令一致,方便脚本消费gridformula selftest 一条命令验证安装正确性,无需 pytestpython build.py 只用标准库产出 wheel + sdist + SHA256SUMSeval、无外部进程调用,可放心跑在隔离环境里环境要求:Python 3.8 – 3.13;Windows / macOS / Linux 任意;不需要联网、不需要密钥、不需要编译。
# 1️⃣ 克隆(或直接下载源码) git clone https://github.com/gitstq/GridFormula.git cd GridFormula # 2️⃣ 零依赖自检(应该输出 26/26 通过) python -m gridformula selftest # 3️⃣ 生成一份可直接运行的示例 CSV python -m gridformula init -o demo.csv # 4️⃣ 求值! python -m gridformula eval -i demo.csv --format markdown
也可以作为库安装(运行时仍然是 0 个依赖):
pip install . # 标准安装 gridformula functions # 安装后可直接用命令
或用零依赖构建产物安装:
python build.py # 产出 dist/*.whl 与 dist/SHA256SUMS
pip install dist/gridformula-1.0.0-py3-none-any.whl作为 Python 库调用:
from gridformula import evaluate wb, ev = evaluate(csv_text="单价,数量,小计\n12.5,3,=A2*B2\n") print(ev.cache["C2"]) # 37.5 print(wb.to_csv(ev.cache)) # 导出计算后的 CSV
📷 运行截图占位:
gridformula eval -i examples/sales.csv --format markdown的终端输出表格(见 examples/README.md)。 🎞️ 演示动图占位:init → eval → lint → trace四步流程录屏,将在后续版本补充。
| 单元格内容 | 含义 |
|---|---|
12.5 |
数字字面量 |
TRUE / FALSE |
布尔字面量 |
笔记本 |
文本字面量 |
| 空 | 空白(算术中按 0 处理) |
=B2*C2 |
公式(前导 = 是公式标记) |
CSV 默认以逗号分列,而 IF(a,b,c) 本身也含逗号,直接写会被 CSV 解析器拆成多列。引擎同时支持逗号与分号,因此示例统一使用分号:
商品,单价,小计 笔记本,12.5,=IF(B2>10;"贵";"便宜")
若坚持用逗号,请按 CSV 规则把整个字段用双引号包裹,并把公式内的双引号翻倍:
商品,单价,小计 笔记本,12.5,"=IF(B2>10,""贵"",""便宜"")"
| 命令 | 作用 | 常用参数 |
|---|---|---|
eval |
求值并输出整张表 | -i / --set / --format / --strict |
lint |
静态体检(不求值) | -i / --format / --strict |
trace |
求值顺序与依赖链 | -i / --cell / --format |
functions |
列出全部内置函数 | --format |
init |
生成示例 CSV | -o |
selftest |
内置自检 | 无 |
# 覆盖或新增公式单元格(注意 CELL 后再跟一个 =) python -m gridformula eval -i demo.csv --set 'G1==SUM(D2:D4)' # 只看某个单元格的依赖链 python -m gridformula trace -i demo.csv --cell E5 --format markdown # 输出 JSON 给其他程序消费 python -m gridformula eval -i examples/sales.csv --format json -o result.json # 从标准输入读取(管道友好) cat examples/budget.csv | python -m gridformula eval --format csv # 自定义分隔符(如分号分隔的 CSV) python -m gridformula eval -i data.csv --delimiter ';'
| 分类 | 代表函数 |
|---|---|
| 🔢 数学 | SUM PRODUCT SUMSQ ABS ROUND ROUNDUP ROUNDDOWN CEILING FLOOR MOD POWER SQRT EXP LN LOG PI INT TRUNC SIGN |
| 📈 统计 | AVERAGE MEDIAN MIN MAX COUNT COUNTA COUNTBLANK |
| 🔀 逻辑 | IF AND OR NOT TRUE FALSE IFERROR NA |
| ℹ️ 信息 | ISERROR ISBLANK ISNUMBER ISTEXT |
| 🔤 文本 | LEN UPPER LOWER TRIM CONCAT CONCATENATE LEFT RIGHT MID FIND SUBSTITUTE REPT EXACT VALUE |
| 🎯 条件 / 查找 | COUNTIF SUMIF VLOOKUP |
完整清单(含参数个数与分类):
python -m gridformula functions --format markdown
🚫 刻意不提供
RAND/NOW/TODAY等易失函数——这是保证结果可在 CI 中复现的核心设计,不是功能缺失。
| 编号 | 级别 | 检查内容 |
|---|---|---|
| GF000 | error | 公式语法错误 |
| GF001 | error | 区域起止倒置 / 引用越界 |
| GF002 | error | 除以字面量零 |
| GF003 | error | 未注册函数名 |
| GF004 | error | 参数个数不合法 |
| GF005 | warning | 空参数 |
| GF006 | error | 自引用 / 区域包含自身 |
| GF007 | info | 魔法数字过多 |
| GF008 | warning | 文本字面量参与算术 |
| GF009 | warning | 嵌套过深 |
| GF010 | warning | 数字与文本混合比较 |
| GF011 | info | 引用空白单元格 |
| GF012 | warning | 公式过长 |
python -m gridformula lint -i examples/sales.csv --strict
| 退出码 | 含义 |
|---|---|
0 |
成功 |
1 |
存在错误值 / error 级 lint 项且启用 --strict |
2 |
输入或配置错误(文件不存在、CSV 非法、--set 格式错误) |
可选环境变量(见 .env.example,默认完全不需要配置):
| 变量 | 作用 |
|---|---|
GRIDFORMULA_FORMAT |
默认输出格式 text / json / markdown / csv |
GRIDFORMULA_STRICT |
设为 1 等价于全局 --strict |
GRIDFORMULA_DELIMITER |
默认 CSV 分隔符 |
eval --strict,公式出错直接让流水线失败lint 检查一份历史表格里的除零、自引用和隐式类型转换SHA256SUMS 做结果留痕设计理念:把「表格计算」降维成离线、确定性、可复现的纯函数求值。所有不确定性来源(随机数、当前时间、网络、外部进程、eval)都被主动移除,换来的是可以在 CI、沙箱、离线环境里放心执行的结果。
技术选型原因:
| 选择 | 原因 |
|---|---|
| 纯标准库 | 零安装摩擦、零供应链风险、审计面最小 |
| 递归下降 + 优先级爬升 | 公式语法小且明确,手写解析器比引入 AST 库更可控 |
| 不可变 AST dataclass | 便于缓存、lint 匹配与求值轨迹记录 |
| 深度优先求值 + 访问集合 | 自然得到拓扑顺序,环检测只需一个 visiting 集合 |
| CSV 而非 xlsx | 文本、可 diff、可版本控制,无需二进制解析依赖 |
| 错误值作为一等值 | 与真实表格语义一致,传播逻辑集中且可测试 |
迭代规划:
INDEX / MATCH / HLOOKUP)、SUMIFS / COUNTIFS 多条件.xlsx 单工作表读取(仍保持零依赖,仅解析必要 XML)项目类型:CLI 工具 / Python 脚本库(非桌面应用、非可执行程序)。按发布规范,本项目无需上传 Release 附件,这里给出完整的安装、引入、集成与兼容环境说明。
python build.py # 产出 wheel + sdist + SHA256SUMS python build.py verify # 逐条校验 wheel 内 RECORD 的 sha256 与大小
产物位于 dist/:
| 文件 | 说明 |
|---|---|
gridformula-1.0.0-py3-none-any.whl |
纯 Python wheel,py3-none-any,跨平台通用 |
gridformula-1.0.0.tar.gz |
sdist 源码包 |
SHA256SUMS |
两个产物的校验和 |
构建脚本不使用 setuptools / wheel / build,也不需要联网;它固定归档时间戳并排序条目,因此相同源码产出逐字节一致的压缩包。校验方法:
sha256sum -c SHA256SUMS # Linux / macOS| 场景 | 做法 |
|---|---|
| 🖥️ 本地命令行 | pip install dist/*.whl 后使用 gridformula 命令 |
| 🐍 作为库引入 | from gridformula import evaluate, lint_workbook |
| 🤖 CI / 流水线 | 直接把 gridformula/ 目录放进仓库,用 python -m gridformula ...,零安装 |
| 🐳 容器 | 任意 python:3.x-slim 基础镜像,复制源码即可,无需 pip install |
| 📴 完全离线 | 复制源码目录即可运行;不联网、不读密钥、不写用户目录 |
| 项 | 范围 |
|---|---|
| Python | 3.8 / 3.9 / 3.10 / 3.11 / 3.12 / 3.13 |
| 操作系统 | Windows / macOS / Linux(纯 Python,无平台相关代码) |
| 终端 | 任意支持 UTF-8 的终端 |
| 依赖 | 0 个运行时依赖;pytest 仅为开发期可选 |
| 网络 | 完全不需要 |
⚠️ 本仓库不提供 Windows / macOS / Linux 原生可执行文件:项目属于脚本库类,按发布规范无需全平台打包,也避免上传无法验证的二进制产物。
欢迎 PR 与 Issue!完整规范见 CONTRIBUTING.md。
feat: / fix: / docs: / test: / refactor: / chore:python -m gridformula selftest 与 python -m pytest -qeval本项目采用 MIT License,详见 LICENSE。
GridFormula 是一套以純 Python 標準庫實作的試算表公式解析與求值引擎。它把一份普通的 CSV 當成工作表:以 = 開頭的儲存格是公式,其餘是數字、布林值或文字;執行一條指令,就能取得整張表的計算結果。
它處理的是一類具體卻反覆出現的痛點:
| 痛點 | 現況 | GridFormula 的做法 |
|---|---|---|
| 📦 表格引擎太重 | Office SDK 功能強,但依賴多、體積大,塞不進 CI 或離線腳本 | 0 個第三方依賴,單一目錄即可執行 |
| 🔁 結果不可重現 | RAND / NOW 等易變函數讓同一份表每次算出不同結果 |
只提供確定性純函數,同輸入逐位元組可重現 |
| 🕳️ 錯誤難定位 | 一個 #VALUE! 傳遍全表,卻找不到源頭 |
完整錯誤值模型 + 求值軌跡呈現依賴鏈與計算順序 |
| 🔄 循環參照卡死 | 樸素遞迴遇到 A1=B1+1; B1=A1+1 會堆疊溢位 |
深度優先偵測環,確定性地收斂為 #CIRCLE! |
| 🐼 為了算一欄引入 pandas | 只想按欄加總,卻要裝數百 MB 依賴 | CSV 即工作表,=SUM(B2:B9) 直接寫進儲存格 |
自研差異化亮點:零依賴純標準庫、刻意不實作易變函數以確保確定性、錯誤值沿依賴鏈傳播、13 條靜態体检規則、可稽核求值軌跡、四種輸出格式、CI 原生結束碼,以及用標準庫直接產出逐位元組可重現的 wheel / sdist。
💡 靈感來源:GitHub Trending 上的
dream-num/univer(Office SDK)、we-promise/sure(個人理財)與louislam/uptime-kuma(自架監控)共同指向的「輕量、內嵌、可重現的表格計算」需求。 ⚖️ 僅參考產品邏輯與所解決的痛點,程式碼 100% 獨立自研,未複製任何第三方實作。
& 串接、% 百分比、^ 次方(右結合)、括號、A1:C9 範圍、$A$1 絕對參照SUMIF、COUNTIF、VLOOKUP、IFERROR#CIRCLE!#DIV/0! #VALUE! #REF! #NAME? #NUM! #N/A #PARSE! #CIRCLE!,沿鏈傳播且可被 IFERROR 攔截trace 子指令輸出每個公式儲存格的依賴清單與計算順序,除錯一目了然text / json / markdown / csv,所有子指令一致,方便腳本取用gridformula selftest 一條指令驗證安裝正確性,無需 pytestpython build.py 只用標準庫產出 wheel + sdist + SHA256SUMSeval、無外部行程呼叫,可安心跑在隔離環境環境需求:Python 3.8 – 3.13;Windows / macOS / Linux 皆可;不需要連網、不需要金鑰、不需要編譯。
# 1️⃣ 取得原始碼 git clone https://github.com/gitstq/GridFormula.git cd GridFormula # 2️⃣ 零依賴自檢(應輸出 26/26 通過) python -m gridformula selftest # 3️⃣ 產生可直接執行的範例 CSV python -m gridformula init -o demo.csv # 4️⃣ 求值! python -m gridformula eval -i demo.csv --format markdown
也可以當成套件安裝(執行期仍是 0 個依賴):
pip install .
gridformula functions或使用零依賴建置產物:
python build.py pip install dist/gridformula-1.0.0-py3-none-any.whl
作為 Python 套件呼叫:
from gridformula import evaluate wb, ev = evaluate(csv_text="單價,數量,小計\n12.5,3,=A2*B2\n") print(ev.cache["C2"]) # 37.5 print(wb.to_csv(ev.cache)) # 匯出計算後的 CSV
📷 執行截圖預留位置:
gridformula eval -i examples/sales.csv --format markdown的終端表格輸出(見 examples/README.md)。 🎞️ 示範動圖預留位置:init → eval → lint → trace四步流程錄影,將於後續版本補上。
| 儲存格內容 | 意義 |
|---|---|
12.5 |
數字常值 |
TRUE / FALSE |
布林常值 |
筆記本 |
文字常值 |
| 空 | 空白(算術中視為 0) |
=B2*C2 |
公式(前置 = 是公式標記) |
CSV 預設以逗號分欄,而 IF(a,b,c) 本身也含逗號,直接寫會被 CSV 解析器拆成多欄。引擎同時支援逗號與分號,因此範例統一使用分號:
商品,單價,小計 筆記本,12.5,=IF(B2>10;"貴";"便宜")
若堅持使用逗號,請依 CSV 規則以雙引號包住整個欄位,並把公式內的雙引號加倍:
商品,單價,小計 筆記本,12.5,"=IF(B2>10,""貴"",""便宜"")"
| 指令 | 作用 | 常用參數 |
|---|---|---|
eval |
求值並輸出整張表 | -i / --set / --format / --strict |
lint |
靜態体检(不求值) | -i / --format / --strict |
trace |
求值順序與依賴鏈 | -i / --cell / --format |
functions |
列出全部內建函數 | --format |
init |
產生範例 CSV | -o |
selftest |
內建自檢 | 無 |
# 覆寫或新增公式儲存格(注意 CELL 後還要再接一個 =) python -m gridformula eval -i demo.csv --set 'G1==SUM(D2:D4)' # 只看某個儲存格的依賴鏈 python -m gridformula trace -i demo.csv --cell E5 --format markdown # 輸出 JSON 給其他程式取用 python -m gridformula eval -i examples/sales.csv --format json -o result.json # 從標準輸入讀取(管線友善) cat examples/budget.csv | python -m gridformula eval --format csv # 自訂分隔符號 python -m gridformula eval -i data.csv --delimiter ';'
| 分類 | 代表函數 |
|---|---|
| 🔢 數學 | SUM PRODUCT SUMSQ ABS ROUND ROUNDUP ROUNDDOWN CEILING FLOOR MOD POWER SQRT EXP LN LOG PI INT TRUNC SIGN |
| 📈 統計 | AVERAGE MEDIAN MIN MAX COUNT COUNTA COUNTBLANK |
| 🔀 邏輯 | IF AND OR NOT TRUE FALSE IFERROR NA |
| ℹ️ 資訊 | ISERROR ISBLANK ISNUMBER ISTEXT |
| 🔤 文字 | LEN UPPER LOWER TRIM CONCAT CONCATENATE LEFT RIGHT MID FIND SUBSTITUTE REPT EXACT VALUE |
| 🎯 條件 / 查找 | COUNTIF SUMIF VLOOKUP |
完整清單(含參數個數與分類):
python -m gridformula functions --format markdown
🚫 刻意不提供
RAND/NOW/TODAY等易變函數——這是確保結果可在 CI 重現的核心設計,並非功能缺漏。
| 編號 | 級別 | 檢查內容 |
|---|---|---|
| GF000 | error | 公式語法錯誤 |
| GF001 | error | 範圍起迄倒置 / 參照越界 |
| GF002 | error | 除以常值零 |
| GF003 | error | 未註冊函數名稱 |
| GF004 | error | 參數個數不合法 |
| GF005 | warning | 空參數 |
| GF006 | error | 自參照 / 範圍包含自身 |
| GF007 | info | 魔法數字過多 |
| GF008 | warning | 文字常值參與算術 |
| GF009 | warning | 巢狀過深 |
| GF010 | warning | 數字與文字混合比較 |
| GF011 | info | 參照空白儲存格 |
| GF012 | warning | 公式過長 |
python -m gridformula lint -i examples/sales.csv --strict
| 結束碼 | 意義 |
|---|---|
0 |
成功 |
1 |
存在錯誤值 / error 級体检項目且啟用 --strict |
2 |
輸入或設定錯誤(檔案不存在、CSV 不合法、--set 格式錯誤) |
選用環境變數(見 .env.example,預設完全不需要設定):
| 變數 | 作用 |
|---|---|
GRIDFORMULA_FORMAT |
預設輸出格式 text / json / markdown / csv |
GRIDFORMULA_STRICT |
設為 1 等同全域 --strict |
GRIDFORMULA_DELIMITER |
預設 CSV 分隔符號 |
eval --strict,公式出錯直接讓流水線失敗lint 檢查歷史表格中的除零、自參照與隱含型別轉換SHA256SUMS 為結果留痕設計理念:把「表格計算」降維成離線、確定性、可重現的純函數求值。所有不確定性來源(隨機數、當前時間、網路、外部行程、eval)都被主動移除,換來的是能在 CI、沙箱、離線環境安心執行的結果。
技術選型原因:
| 選擇 | 原因 |
|---|---|
| 純標準庫 | 零安裝摩擦、零供應鏈風險、稽核面最小 |
| 遞迴下降 + 優先級爬升 | 公式語法小且明確,手寫解析器比引入 AST 套件更可控 |
| 不可變 AST dataclass | 便於快取、規則比對與求值軌跡記錄 |
| 深度優先求值 + 訪問集合 | 自然得到拓撲順序,偵環只需一個 visiting 集合 |
| CSV 而非 xlsx | 純文字、可 diff、可版本控制,無需二進位解析依賴 |
| 錯誤值作為一等值 | 與真實表格語意一致,傳播邏輯集中且可測試 |
迭代規劃:
INDEX / MATCH / HLOOKUP)、SUMIFS / COUNTIFS 多條件.xlsx 單工作表讀取(仍保持零依賴,僅解析必要 XML)專案類型:CLI 工具 / Python 指令檔庫(非桌面應用、非可執行程式)。依發布規範,本專案無需上傳 Release 附件,此處提供完整的安裝、引入、整合與相容環境說明。
python build.py # 產出 wheel + sdist + SHA256SUMS python build.py verify # 逐條校驗 wheel 內 RECORD 的 sha256 與大小
產物位於 dist/:
| 檔案 | 說明 |
|---|---|
gridformula-1.0.0-py3-none-any.whl |
純 Python wheel,py3-none-any,跨平台通用 |
gridformula-1.0.0.tar.gz |
sdist 原始碼包 |
SHA256SUMS |
兩個產物的校驗和 |
建置腳本不使用 setuptools / wheel / build,也不需要連網;它固定封存時間戳並排序項目,因此相同原始碼產出逐位元組一致的壓縮檔。校驗方式:
sha256sum -c SHA256SUMS # Linux / macOS| 情境 | 做法 |
|---|---|
| 🖥️ 本機指令列 | pip install dist/*.whl 後使用 gridformula 指令 |
| 🐍 作為套件引入 | from gridformula import evaluate, lint_workbook |
| 🤖 CI / 流水線 | 直接把 gridformula/ 目錄放進專案,用 python -m gridformula ...,零安裝 |
| 🐳 容器 | 任意 python:3.x-slim 基礎映像,複製原始碼即可,無需 pip install |
| 📴 完全離線 | 複製原始碼目錄即可執行;不連網、不讀金鑰、不寫使用者目錄 |
| 項目 | 範圍 |
|---|---|
| Python | 3.8 / 3.9 / 3.10 / 3.11 / 3.12 / 3.13 |
| 作業系統 | Windows / macOS / Linux(純 Python,無平台相關程式碼) |
| 終端機 | 任何支援 UTF-8 的終端機 |
| 依賴 | 0 個執行期依賴;pytest 僅為開發期選用 |
| 網路 | 完全不需要 |
⚠️ 本專案不提供 Windows / macOS / Linux 原生可執行檔:屬於指令檔庫類,依發布規範無需全平台打包,也避免上傳無法驗證的二進位產物。
歡迎 PR 與 Issue!完整規範見 CONTRIBUTING.md。
feat: / fix: / docs: / test: / refactor: / chore:python -m gridformula selftest 與 python -m pytest -qeval本專案採用 MIT License,詳見 LICENSE。
GridFormula is a spreadsheet formula parser and evaluation engine written entirely with the Python standard library. It treats an ordinary CSV file as a worksheet: cells starting with = are formulas, everything else is a number, boolean or string. One command computes the whole sheet.
It addresses a narrow but recurring set of pains:
| Pain | Status quo | GridFormula |
|---|---|---|
| 📦 Office SDKs are heavy | Powerful, but too many dependencies for a CI job or an offline script | Zero third-party dependencies, runs from a single directory |
| 🔁 Results are not reproducible | Volatile functions like RAND / NOW change the answer on every run |
Deterministic pure functions only; byte-for-byte reproducible output |
| 🕳️ Errors are hard to trace | One #VALUE! spreads across the sheet with no clue where it started |
First-class error values plus an evaluation trace showing the dependency chain |
| 🔄 Circular references hang things | Naive recursion blows the stack on A1=B1+1; B1=A1+1 |
Depth-first cycle detection resolving deterministically to #CIRCLE! |
| 🐼 pandas just to sum a column | Hundreds of megabytes for one aggregation | CSV is the worksheet — write =SUM(B2:B9) directly in a cell |
What makes it different: standard-library only, deliberately no volatile functions, error values that propagate along dependency chains, 13 static lint rules, an auditable evaluation trace, four output formats, CI-native exit codes, and a standard-library build that produces byte-for-byte reproducible wheel / sdist artifacts.
💡 Inspiration: the "lightweight, embeddable, reproducible spreadsheet calculation" need shared by GitHub Trending projects such as
dream-num/univer(Office SDK),we-promise/sure(personal finance) andlouislam/uptime-kuma(self-hosted monitoring). ⚖️ Only the product logic and the problem space were referenced. The code is 100% independently written; no third-party implementation was copied.
& concatenation, % percent, ^ power (right-associative), parentheses, A1:C9 ranges, $A$1 absolute referencesSUMIF, COUNTIF, VLOOKUP and IFERROR#CIRCLE!#DIV/0! #VALUE! #REF! #NAME? #NUM! #N/A #PARSE! #CIRCLE!, propagating along the chain and interceptable with IFERRORtrace subcommand reports each formula cell's dependencies and computation ordertext / json / markdown / csv, consistent across all subcommandsgridformula selftest verifies an installation without pytestpython build.py emits wheel + sdist + SHA256SUMS using only the standard libraryeval, no subprocesses — safe to run in isolated environmentsRequirements: Python 3.8 – 3.13; Windows / macOS / Linux; no network access, no credentials, no compilation.
# 1️⃣ Get the source git clone https://github.com/gitstq/GridFormula.git cd GridFormula # 2️⃣ Dependency-free self-check (should report 26/26) python -m gridformula selftest # 3️⃣ Generate a ready-to-run sample CSV python -m gridformula init -o demo.csv # 4️⃣ Evaluate python -m gridformula eval -i demo.csv --format markdown
Install as a package (still zero runtime dependencies):
pip install .
gridformula functionsOr install from the zero-dependency build artifacts:
python build.py pip install dist/gridformula-1.0.0-py3-none-any.whl
Use it as a library:
from gridformula import evaluate wb, ev = evaluate(csv_text="price,qty,subtotal\n12.5,3,=A2*B2\n") print(ev.cache["C2"]) # 37.5 print(wb.to_csv(ev.cache)) # export the computed CSV
📷 Screenshot placeholder: terminal table from
gridformula eval -i examples/sales.csv --format markdown(see examples/README.md). 🎞️ Demo GIF placeholder: a four-stepinit → eval → lint → tracewalkthrough, planned for a later release.
| Cell content | Meaning |
|---|---|
12.5 |
Number literal |
TRUE / FALSE |
Boolean literal |
Notebook |
Text literal |
| empty | Blank (treated as 0 in arithmetic) |
=B2*C2 |
Formula (the leading = marks a formula) |
CSV splits columns on commas, but IF(a,b,c) contains commas too. Writing it naively would break the formula across several columns. The engine accepts both commas and semicolons, so all examples use semicolons:
item,price,verdict Notebook,12.5,=IF(B2>10;"Expensive";"Cheap")
If you prefer commas, quote the whole CSV field and double the inner quotes:
item,price,verdict Notebook,12.5,"=IF(B2>10,""Expensive"",""Cheap"")"
| Command | Purpose | Common options |
|---|---|---|
eval |
Evaluate and print the whole sheet | -i / --set / --format / --strict |
lint |
Static checks, no evaluation | -i / --format / --strict |
trace |
Evaluation order and dependency chains | -i / --cell / --format |
functions |
List every built-in function | --format |
init |
Generate a sample CSV | -o |
selftest |
Built-in self-check | none |
# Override or add a formula cell (note the second = after the cell address) python -m gridformula eval -i demo.csv --set 'G1==SUM(D2:D4)' # Inspect one cell's dependency chain python -m gridformula trace -i demo.csv --cell E5 --format markdown # Emit JSON for downstream tooling python -m gridformula eval -i examples/sales.csv --format json -o result.json # Read from stdin (pipeline friendly) cat examples/budget.csv | python -m gridformula eval --format csv # Custom delimiter python -m gridformula eval -i data.csv --delimiter ';'
| Category | Representative functions |
|---|---|
| 🔢 Math | SUM PRODUCT SUMSQ ABS ROUND ROUNDUP ROUNDDOWN CEILING FLOOR MOD POWER SQRT EXP LN LOG PI INT TRUNC SIGN |
| 📈 Statistics | AVERAGE MEDIAN MIN MAX COUNT COUNTA COUNTBLANK |
| 🔀 Logic | IF AND OR NOT TRUE FALSE IFERROR NA |
| ℹ️ Information | ISERROR ISBLANK ISNUMBER ISTEXT |
| 🔤 Text | LEN UPPER LOWER TRIM CONCAT CONCATENATE LEFT RIGHT MID FIND SUBSTITUTE REPT EXACT VALUE |
| 🎯 Conditional / lookup | COUNTIF SUMIF VLOOKUP |
Full list (with argument counts and categories):
python -m gridformula functions --format markdown
🚫 Volatile functions such as
RAND/NOW/TODAYare intentionally omitted — this is the design decision that keeps results reproducible in CI, not a missing feature.
| Code | Severity | Check |
|---|---|---|
| GF000 | error | Formula syntax error |
| GF001 | error | Inverted range / out-of-bounds reference |
| GF002 | error | Division by a literal zero |
| GF003 | error | Unregistered function name |
| GF004 | error | Invalid argument count |
| GF005 | warning | Empty argument |
| GF006 | error | Self-reference / range containing the formula cell |
| GF007 | info | Too many magic numbers |
| GF008 | warning | Text literal used in arithmetic |
| GF009 | warning | Excessive nesting |
| GF010 | warning | Mixed number/text comparison |
| GF011 | info | Reference to a blank cell |
| GF012 | warning | Overlong formula |
python -m gridformula lint -i examples/sales.csv --strict
| Exit code | Meaning |
|---|---|
0 |
Success |
1 |
Error values present / error-level lint findings with --strict |
2 |
Input or configuration error (missing file, invalid CSV, malformed --set) |
Optional environment variables (see .env.example — no configuration is needed by default):
| Variable | Purpose |
|---|---|
GRIDFORMULA_FORMAT |
Default output format: text / json / markdown / csv |
GRIDFORMULA_STRICT |
Set to 1 for a global --strict |
GRIDFORMULA_DELIMITER |
Default CSV delimiter |
eval --strict on a CSV report in CI so a broken formula fails the pipelinelint to find division by zero, self-references and implicit coercion in legacy sheetsSHA256SUMS for an audit trailDesign principle: reduce "spreadsheet calculation" to an offline, deterministic, reproducible pure-function evaluation. Every source of nondeterminism — randomness, wall-clock time, network, subprocesses, eval — is deliberately removed, so results are safe to run in CI, sandboxes and air-gapped environments.
Why these choices:
| Choice | Reason |
|---|---|
| Standard library only | No install friction, no supply-chain surface, minimal audit scope |
| Recursive descent + precedence climbing | The grammar is small and well-defined; a hand-written parser is more controllable than an AST dependency |
| Immutable AST dataclasses | Easy caching, lint matching and trace recording |
| Depth-first evaluation + a visiting set | Naturally yields topological order; cycle detection needs only one set |
| CSV instead of xlsx | Text, diffable, version-controllable, no binary parsing dependency |
| Error values as first-class values | Matches real spreadsheet semantics; propagation logic is centralized and testable |
Roadmap:
INDEX / MATCH / HLOOKUP) and multi-condition SUMIFS / COUNTIFS.xlsx reading (still zero-dependency, parsing only the necessary XML)Project type: CLI tool / Python script library — not a desktop application or a native executable. Per the release policy, no Release binary assets are required; complete installation, integration and compatibility guidance is provided here instead.
python build.py # emits wheel + sdist + SHA256SUMS python build.py verify # verifies every RECORD sha256 and file size inside the wheel
Artifacts in dist/:
| File | Description |
|---|---|
gridformula-1.0.0-py3-none-any.whl |
Pure-Python wheel, py3-none-any, platform independent |
gridformula-1.0.0.tar.gz |
sdist source archive |
SHA256SUMS |
Checksums for both artifacts |
The build script uses no setuptools / wheel / build and needs no network. It pins archive timestamps and sorts entries, so identical source yields byte-identical archives. Verify with:
sha256sum -c SHA256SUMS # Linux / macOS| Scenario | How |
|---|---|
| 🖥️ Local CLI | pip install dist/*.whl, then use the gridformula command |
| 🐍 As a library | from gridformula import evaluate, lint_workbook |
| 🤖 CI / pipelines | Drop the gridformula/ directory into the repo and run python -m gridformula ... — zero install |
| 🐳 Containers | Any python:3.x-slim base image; copy the source, no pip install needed |
| 📴 Fully offline | Copy the source directory; no network, no credential reads, no writes to user directories |
| Item | Range |
|---|---|
| Python | 3.8 / 3.9 / 3.10 / 3.11 / 3.12 / 3.13 |
| OS | Windows / macOS / Linux (pure Python, no platform-specific code) |
| Terminal | Any UTF-8 capable terminal |
| Dependencies | 0 runtime dependencies; pytest is dev-only and optional |
| Network | Not required at all |
⚠️ No native Windows / macOS / Linux executables are shipped: this is a script library, so per the release policy no cross-platform binaries are produced — and no unverifiable binary artifacts are uploaded.
PRs and issues are welcome. Full guidelines live in CONTRIBUTING.md.
feat: / fix: / docs: / test: / refactor: / chore:python -m gridformula selftest and python -m pytest -qevalReleased under the MIT License — see LICENSE.
gitstq/GridFormula is a public repo on GitHub by gitstq. Zero-dependency, offline, deterministic spreadsheet formula engine for CSV worksheets.
It declares the MIT license on GitHub.
Its maker has not tagged a system, so it is unknown here. Its README says what it needs.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-11-15. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.
Reverse engineer anything with agents, from app behavior down to native binaries.

✨ Innovative and open-source visualization application that transforms various data formats, such as JSON, YAML, XML and CSV into interactive graphs.

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
📗 SheetJS Spreadsheet Data Toolkit -- New home https://git.sheetjs.com/SheetJS/sheetjs
ADB 驱动的 Android 虚拟定位 CLI:常驻推送、坐标系统一换算、GPX 轨迹回放。零 npm 依赖,无需 root。
🔬 HexScope — 零依赖·离线优先的二进制文件取证探查工具箱 | Zero-dependency binary forensics workbench: hex dump, magic detection, entropy, strings, histogram, binary diff & file carving
BlueEagle AI Gateway | 蓝鹰AI网关 - Cheapest AI API Gateway | 0.09x cost | 1:1 recharge | GPT-4o Claude Gemini DeepSeek | OpenAI compatible | 最便宜AI中转站
Cheapest AI API Gateway | GPT-4o/Claude/Gemini at 0.09x cost | 1:1 CNY:USD recharge | 100% official pool | OpenAI compatible | ahg.codes
🛡️ Offline-first, zero-dependency decision cards & session handoff protocol for AI agents | AI Agent 决策卡与会话交接协议 · Go 单二进制 · 六平台
🦅 蓝鹰AI网关 | 0.09x Cheapest AI API Gateway | GPT-4o Claude 4 Gemini 2.5 DeepSeek | 1:1充值 100%官方号池 | AI大模型中转站 API Proxy
This page is also available as structured data, with the same sources and dates.
/api/v1/resources/gh/gitstq/GridFormulaTake My Repo has not tested this on your machine. Requirements come from the project's own documentation.