python-calamine：rust实现的读取excel高性能库-马育民老师

# 介绍
`python-calamine` 是 **Rust 库 calamine 的 Python 绑定**，专门用于**高速读取电子表格文件**，**只支持读，不支持写入/修改Excel**，是 pandas 2.2+ 内置的官方 `calamine` 引擎底层依赖。

### 底层

Rust calamine + PyO3 + Maturin 打包，预编译二进制包，无需本地编译Rust环境。

### 支持文件格式

- **`.xlsx` 普通Excel**
- `.xlsm` 带宏Excel
- `.xlsb` 二进制Excel（重点优势：能正确识别xlsb里的日期，pyxlsb做不到）
- **`.xls` 旧版Excel97**
- `.ods` OpenDocument 表格（LibreOffice）

### 优势
1. **速度极快**
    基准测试：比 openpyxl 快约5倍，odf快20倍，pyxlsb快4倍，xlrd快约1.5倍；大文件、百万单元格场景优势明显，内存占用更低。
    **注意：**只读取少量几行时，openpyxl/pyxlsb的懒加载会更快。
2. **跨平台、无Office依赖**
    Windows/Linux/macOS都能用，**不需要安装微软Office、LibreOffice**。
3. **原生类型识别**
    单元格自动区分：整数、浮点数、字符串、布尔、日期时间、空单元格、错误值，不是全部转为字符串。
4. **和pandas无缝集成**
    pandas `read_excel` 直接指定 `engine="calamine"` 即可使用，无需额外复杂适配。

### 限制
1. **只读！不能写Excel**，无法新建、修改、保存文件；写文件依旧用 openpyxl / xlsxwriter。
2. 对**合并单元格**支持有限（新版底层rust calamine已支持，但python binding版本要看发布状态）。
3. 不支持Excel公式计算（只能读取公式**结果值**，拿不到公式文本）。
4. 不支持图表、宏脚本、单元格样式、颜色、批注等富格式信息，只读取单元格数据。

# 安装

### pip
```bash
pip install python-calamine
```

### uv

```bash
uv add python-calamine
```

# 基础使用例子

```python
from python_calamine import CalamineWorkbook

# 打开工作簿
wb = CalamineWorkbook.from_path("test.xlsx")

# 获取所有工作表名称
print(wb.sheet_names)

# 通过工作表名获取sheet对象
sheet = wb.get_sheet_by_name("Sheet1")

# 读取全部数据，返回二维列表
data = sheet.to_python()
for row in data:
    print(row)

# 默认会自动跳过前面空白行列；关闭自动跳过
sheet = wb.get_sheet_by_name("Sheet1", skip_empty_area=False)
```

# 在 Pandas 中使用（最常用场景）

`pandas >=2.2` 原生内置calamine引擎，装好python-calamine即可直接调用

```python
import pandas as pd

# 读取xlsb/xlsx/xls/ods
df = pd.read_excel(
    "data.xlsb",
    engine="calamine",
    usecols="A:C",  # 只读取指定列
    nrows=1000      # 只读前N行
)
print(df.head())
```

# 单元格数据类型
calamine底层会返回枚举类型，python-calamine自动映射：

- Int → int
- Float → float
- String → str
- Bool → bool
- DateTime → datetime.datetime
- Empty → None
- Error → 错误标记（Excel单元格报错值）

# 和其他Excel读取库对比

|库|底层|读写|优点|缺点|
|---|---|---|---|---|
|python-calamine|Rust|只读|速度快、支持xlsb日期、跨平台|不可写，无样式/公式|
|openpyxl|Pure Python|读写|功能最全，支持样式、公式|大文件慢、内存高|
|xlrd|C/Python|只读|老牌稳定|新版不再支持xlsx|
|pyxlsb|C|只读|读取xlsb|xlsb日期识别差|

# 适用场景

- 大批量Excel数据采集、数据清洗、ETL、报表导入
- 读取 `.xlsb` 文件（python-calamine最大亮点）
- 跨平台服务端批量解析Excel，不想依赖Office
- 不需要修改/生成Excel文件
- 不需要读取单元格样式、颜色、公式文本、图表

- 支持文件流：可以直接传入bytes，不用落地本地文件
- 适合爬虫、数据中台批量解析大量报表场景

原文出处：/show_1GW4BaInoQPi.html