Metadata-Version: 2.4
Name: excelio
Version: 1.0.0
Summary: 纯 Python 实现的 Excel 文件读写引擎（.xls BIFF8 与 .xlsx OOXML），无第三方依赖
Author-email: YANGUIQIANG <15554663309@163.com>
License-Expression: MIT
Keywords: xls,xlsx,excel,biff8,ooxml,spreadsheet
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# excelio 使用说明

纯 Python 实现的 Excel 文件读写引擎，整合了 `.xls`（BIFF8）与 `.xlsx`（OOXML）两种格式，无任何第三方依赖。

- `.xls` 引擎：`excelio.xls`
- `.xlsx` 引擎：`excelio.xlsx`

---

## 一、安装

```bash
pip install excelio-1.0.0-py3-none-any.whl
```

或直接使用源码：把 `excelio` 目录放到项目路径中（`import excelio` 即可）。

---

## 二、快速开始

```python
import excelio

# 读取：按扩展名自动识别格式
wb = excelio.load_workbook('input.xls')     # 走 xls 引擎
wb = excelio.load_workbook('input.xlsx')    # 走 xlsx 引擎
print(wb.sheet_names)
```

也可以显式指定引擎：

```python
from excelio.xls import Workbook as XlsWorkbook
from excelio.xlsx import Workbook as XlsxWorkbook
```

---

## 三、读取 Excel 文件

```python
import excelio

wb = excelio.load_workbook('data.xls')

# 获取工作表
ws = wb.active_sheet              # 活动工作表
ws = wb.get_sheet('Sheet1')       # 按名称
ws = wb.get_sheet(0)              # 按索引

# 读取单元格（0 基索引）
cell = ws.get_cell(0, 0)
print(cell.value)                 # 单元格值

# A1 样式访问
cell = ws['A1']
print(cell.value)
print(cell.has_formula)           # 是否公式
print(cell.display_value)         # 公式单元格返回缓存值

# 遍历所有单元格
for c in ws.iter_cells():
    print(c.coordinate, c.value)

# 遍历行（每行返回单元格列表）
for row in ws.iter_rows():
    print([c.value if c else None for c in row])

# 尺寸与数量
print(ws.dimensions)              # (min_row, min_col, max_row, max_col)
print(ws.cell_count)
```

---

## 四、创建并写入 Excel 文件

### 4.1 创建 .xls

```python
from excelio.xls import Workbook

wb = Workbook()
ws = wb.create_sheet('Sheet1')

ws['A1'] = 'Hello'
ws['A2'] = 42
ws['A3'] = 3.14
ws['A4'] = True
ws['A5'] = '=SUM(A2:A3)'          # 公式

wb.save('output.xls')
```

### 4.2 创建 .xlsx

```python
from excelio.xlsx import Workbook

wb = Workbook()
ws = wb.create_sheet('Sheet1')

ws['A1'] = 'Hello'
ws['A2'] = 42
ws['A3'] = 3.14
ws['A4'] = True
ws['A5'] = '=SUM(A2:A3)'          # 公式

wb.save('output.xlsx')
```

> 说明：两个引擎的 API 高度一致，主要差异是单元格样式索引字段名
> （`.xls` 用 `xf_index`，`.xlsx` 用 `style_index`）。

---

## 五、单元格操作

```python
ws = wb.create_sheet('Sheet1')

# 使用 set_cell（0 基行列）
ws.set_cell(0, 0, value='文本')
ws.set_cell(1, 0, value=100)
ws.set_cell(2, 0, formula='SUM(A1:A2)')

# 使用 A1 语法
ws['B1'] = '文本'
ws['B2'] = 100
ws['B3'] = '=B1+B2'

# 使用元组（行, 列）
ws[(0, 2)] = 'C1 内容'

# 读取
cell = ws['B1']
print(cell.value)

# 删除
ws.delete_cell(0, 0)
```

---

## 六、样式设置

两个引擎均提供 `Font` / `Border` / `Fill` / `Alignment` / `Style`。

```python
from excelio.xls.styles import Style, Font, Border, Fill, Alignment
# 或 .xlsx：
# from excelio.xlsx import Style, Font, Border, Fill, Alignment

style = Style(
    font=Font(name='微软雅黑', size=12, bold=True, color=0x0A),      # 红色
    alignment=Alignment(horizontal='Center', vertical='Center'),
    border=Border(left_style='Thin', right_style='Thin',
                  top_style='Thin', bottom_style='Thin'),
    fill=Fill(pattern='Solid', fg_color=0x2C, bg_color=0x2C),        # 金色
    number_format='0.00',
)

wb = Workbook()
ws = wb.create_sheet('Sheet1')
xf_index = wb.add_style(style)            # 注册样式，返回样式索引
ws.set_cell(0, 0, value='标题', xf_index=xf_index)   # .xls
# .xlsx 对应为 style_index=wb.add_style(style)
```

### 样式对象参数

| 对象 | 关键参数 |
|------|---------|
| `Font` | `name`(默认 Arial)、`size`(磅)、`bold`、`italic`、`underline`、`color`、`strikeout` |
| `Alignment` | `horizontal`(General/Left/Center/Right/Fill/Justify)、`vertical`(Top/Center/Bottom/Justify)、`wrap_text`、`indent`、`shrink_to_fit`、`rotation` |
| `Border` | `left_style`/`right_style`/`top_style`/`bottom_style`(None/Thin/Medium/Dashed/Dotted/Thick/Double/Hair 等)、`*_color` |
| `Fill` | `pattern`(None/Solid/Medium Gray/...)、`fg_color`、`bg_color` |
| `Style` | `font`、`alignment`、`border`、`fill`、`number_format`(如 '0.00'、'¥#,##0.00'、'0%') |

常用颜色索引：`0x08` 黑、`0x09` 白、`0x0A` 红、`0x0B` 绿、`0x0C` 蓝、`0x0D` 黄、`0x2C` 金。

---

## 七、合并单元格与行列设置

```python
ws = wb.create_sheet('Sheet1')

# 合并单元格（0 基：r1, c1, r2, c2）
ws.merge_cells(0, 0, 0, 4)          # 合并 A1:E1

# 列宽 / 行高
ws.set_column_width(0, 20.0)
ws.set_row_height(0, 30.0)
```

---

## 八、公式

`.xls` 与 `.xlsx` 均支持公式单元格。

```python
ws['A1'] = 10
ws['A2'] = 20
ws['A3'] = '=SUM(A1:A2)'
ws['A4'] = '=IF(A3>0,"正数","非正数")'
```

读取时，公式单元格通过 `cell.has_formula` 判断，`cell.display_value` 取缓存计算结果。

> `.xls` 引擎在保存时会把公式字符串自动编译为 BIFF8 RPN 字节流；
> 读取时会保留原始 RPN，可用 `cell._rpn_data` 获取。

---

## 九、模块结构

```
excelio/
├── __init__.py        # 统一入口：load_workbook 自动路由
├── xls/               # .xls (BIFF8) 引擎
│   ├── models/        # Workbook / Worksheet / Cell
│   ├── io/            # loader / writer
│   ├── biff/          # BIFF 记录
│   ├── formula/       # 公式编译/反编译
│   ├── ole2/          # 复合文件读写
│   └── styles/        # Style / Font / Border / Fill / Alignment
└── xlsx/              # .xlsx (OOXML) 引擎
    ├── models.py
    ├── reader.py
    ├── writer.py
    └── styles.py
```

---

## 十、API 速查

### excelio（顶层）

| 名称 | 说明 |
|------|------|
| `excelio.load_workbook(path)` | 按扩展名自动路由加载（`.xlsx` 走 xlsx，其余走 xls） |
| `excelio.xls` | `.xls` 引擎子模块 |
| `excelio.xlsx` | `.xlsx` 引擎子模块 |

### Workbook（两个引擎通用）

| 方法/属性 | 说明 |
|-----------|------|
| `create_sheet(name)` | 创建工作表 |
| `get_sheet(name_or_index)` | 按名称/索引获取工作表 |
| `active_sheet` / `active` | 活动工作表 |
| `sheet_names` | 所有工作表名 |
| `add_style(style)` | 注册样式，返回样式索引 |
| `save(filepath)` | 保存文件 |

### Worksheet（两个引擎通用）

| 方法/属性 | 说明 |
|-----------|------|
| `get_cell(row, col)` | 获取单元格（不存在返回 None） |
| `set_cell(row, col, value=..., formula=...)` | 写入单元格 |
| `ws['A1']` / `ws[(row, col)]` | A1 或元组访问 |
| `ws['A1'] = value` | 赋值（字符串以 `=` 开头视为公式） |
| `iter_cells()` / `iter_rows()` | 遍历 |
| `merge_cells(r1, c1, r2, c2)` | 合并单元格 |
| `set_column_width(col, width)` / `set_row_height(row, height)` | 行列尺寸 |
| `dimensions` / `cell_count` | 尺寸 / 单元格数 |

### Cell

| 属性 | 说明 |
|------|------|
| `value` | 单元格值 |
| `formula` | 公式字符串 |
| `has_formula` | 是否公式 |
| `cached_value` | 公式缓存结果 |
| `display_value` | 显示值（公式返回缓存值） |
| `coordinate` | A1 坐标 |
| `xf_index` / `style_index` | 样式索引（`.xls` 用 xf_index，`.xlsx` 用 style_index） |
