⚗️ Calchemy

数据炼金术 — 为 DataFrame 列运算设计的声明式 DSL
让业务方、LLM 和技术方说同一种语言

✨ 一行表达式完成列计算

传统 pandas 代码对业务方不可读，也让 LLM 承担不必要的翻译成本。Calchemy 用一行自然语言风格的表达式完成列计算：

业务人员也能看懂的对比

❌ 传统 pandas —— 业务方看不懂的"天书"

df["毛利率"] = (
    df["销售额"] - df["成本"]
) / df["销售额"]
df["毛利率"] = df["毛利率"].apply(
    lambda x: f"{x:.2%}" if pd.notna(x) else x
)

✅ Calchemy —— 业务方直接能读

calc(df, "毛利率 = (销售额 - 成本) / 销售额 >>> %")

业务人员不需要理解 df["毛利率"] = ... 或 apply(lambda x: ...)。Calchemy 表达式本身就是业务语言——毛利率 = (销售额 - 成本) / 销售额，一眼就能看懂并核对。

常见业务场景速查

💡 字段名支持中文（销售额、成本）或常见英文简写（GMV、COGS、DAU），DSL 自动识别。

Calchemy = Calc + Alchemy。把原始数据"炼"成业务指标——这就是数据炼金术。

"Every DataFrame has gold in it. Calchemy helps you extract it."

三方受益

🚀 快速上手

安装

pip install calchemy

或直接将 calchemy/ 目录复制到项目中，仅依赖 pandas 和 numpy。

30 秒示例

import pandas as pd
from calchemy import calc

df = pd.DataFrame({
    "销售额": [100, 200, 0, 400],
    "成本":   [60,  150, 0, 300],
})

# 混合运算 + 百分比格式（字段名直接用中文！）
calc(df, "毛利 = 销售额 - 成本")
calc(df, "毛利率 = 毛利 / 销售额 >>> %")

print(df[["销售额", "成本", "毛利", "毛利率"]])

输出：

   销售额  成本  毛利   毛利率
0    100   60   40  40.00%
1    200  150   50  25.00%
2      0    0    0     nan
3    400  300  100  25.00%

📖 DSL 语法

基础格式

新列名 = 列A <运算符> 列B
新列名 = 列A <运算符> 列B >>> 格式

混合运算（支持括号）

gm_rate = (revenue - cogs) / revenue >>> %
tax = revenue * 0.13

操作数：列名（无引号）或数字常量 运算符：+ - * / ** ^ 函数：abs(列名) log(列名) log(列名, 底数) sqrt(列名) 格式后缀（>>> 后）：%/pct/percent/百分比 → 百分比；省略 → 浮点数

API 列表

💡 简单两操作数运算可用 calc_* helper，混合运算请用 calc()。

🛡️ 错误处理（errors 参数）

所有函数均支持 errors 参数，命名对齐 pd.to_datetime(errors=...)：

# 严格模式：有问题直接报错
calc(df, "rate = a / b", errors='raise')

# 忽略模式：有问题跳过
calc(df, "rate = a / b", errors='ignore')

NaN 处理语义

🔒 安全性

calc() 使用 ast.parse 受限子集解析表达式：

• ✅ 允许：列名（Name）、数字常量（Constant）、四则运算（BinOp）、正负号（UnaryOp）、白名单函数（abs/log/sqrt/root）
• ❌ 禁止：任意函数调用、属性访问、下标、比较运算、eval()

# ❌ 以下表达式会被拒绝
calc(df, 'r = __import__("os").system("ls")')  # 函数调用
calc(df, 'r = a.__class__')                     # 属性访问
calc(df, 'r = a > b')                           # 比较运算

📁 项目结构

calchemy/
├── calchemy/               # 包目录
│   ├── __init__.py         # 公共 API 入口
│   ├── types.py            # 数据结构：CalcStep, CalcResult
│   ├── utils.py            # 校验与格式化工具
│   ├── helpers.py          # 运算 helper（四则运算 + 扩展运算）
│   ├── parse.py            # AST 解析与拆解
│   ├── calc.py             # 混合运算引擎
│   └── chain.py            # 链式调用 API
├── tests/                  # 测试目录
│   ├── __init__.py
│   └── test_calchemy.py   # 测试套件（124 用例）
├── README.md               # 中文文档（本文件）
├── README_EN.md            # English documentation
└── .gitignore

🗺️ 开发路线

🎯 设计原则

1. 零隐式魔法：NaN 处理语义必须通过 errors 参数显式声明
2. 列名即文档：DSL 表达式本身就是业务逻辑的可读文档
3. 防御性优先：类型检查先于运算，精确报错优于强制转换
4. LLM 友好：函数签名和 docstring 以 LLM 直接调用为目标
5. 跨后端可迁移：同一套 DSL 可在不同后端执行（Phase 6）

License

Apache 2.0