Metadata-Version: 2.4
Name: datraxlsx
Version: 0.3.0
Summary: 把 DataFrame 保存为带有 Excel 格式的 XLSX 文件的可复用样式工具
Author: SidneyZhang
Author-email: SidneyZhang <zly@lyzhang.me>
License-Expression: MIT
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pandas>=3.0.3
Requires-Dist: polars>=1.42.1
Requires-Dist: pyarrow>=14.0.0
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# DaTraXLSX

这是一个把DataFrame保存为带有Excel格式的XLSX文件的工具。

## 安装

datraxlsx 需要Python 3.13及以上版本，依赖 openpyxl、pandas、polars。

```bash
# 本地开发安装
pip install -e .

# 或使用 uv
uv add datraxlsx
```

## 核心概念

datraxlsx 由四个可复用的构建块组成：

- `CellStyle` — 可复用单元格样式，聚合 `font`/`fill`/`alignment`/`border`/`number_format` 五个字段（均可选），通过 `apply(cell)` 应用到单元格。
- `RowBorder` — 以"边"描述一行单元格的边框：`top`/`bottom`/`left_edge`/`right_edge`/`inner_vertical`。它会自动区分左右边缘与内部竖线，无需手动处理首尾列。
- `TableTheme` — 聚合 `title`/`header`/`body`/`summary` 四套 `CellStyle` 及其对应 `RowBorder`，外加 `title_height`/`row_height`/`column_width`。`TableTheme.default()` 开箱即用，`.replace(...)` 定制单个字段。
- `ExcelWriter` + `Sheet` — 工作簿与工作表写入器。`ExcelWriter` 持有主题与游标起点，通过 `.sheet(name)` 创建工作表；`Sheet` 提供 `use`/`write_title`/`write_data`/`write_summary`/`write_cell`/`set_column_width` 等方法，支持多 sheet 写入。

## 快速开始

零配置即可写出带标题、表头、数据、合计行的格式化报表：

```python
import pandas as pd
from datraxlsx import ExcelWriter

df = pd.DataFrame({"产品": ["A", "B", "C"], "数量": [10, 20, 30], "金额": [100.5, 200.5, 300.5]})

with ExcelWriter("output.xlsx") as wb:
    ws = wb.sheet("销售")
    ws.use(df)
    ws.write_title("销售报表")
    ws.write_data()
    ws.write_summary(agg_cols=["数量", "金额"], merge_cols=["产品"])
```

polars DataFrame 同样可用，`use()` 会自动转换。

## 复用主题

定义一次主题，跨 sheet、跨文件复用。`TableTheme.default().replace(...)` 只覆盖传入的字段，其余沿用默认值：

```python
from datraxlsx import ExcelWriter, TableTheme, CellStyle, RowBorder
from openpyxl.styles import Font, PatternFill, Side

theme = TableTheme.default().replace(
    header=CellStyle(
        font=Font(name="微软雅黑", size=12, bold=True, color="FFFFFF"),
        fill=PatternFill(patternType="solid", fgColor="0066CC"),
    ),
    header_border=RowBorder(
        top=Side(border_style="thick"),
        bottom=Side(border_style="double"),
    ),
)

with ExcelWriter("output.xlsx", theme=theme) as wb:
    for name, df in sheets.items():
        ws = wb.sheet(name)
        ws.use(df)
        ws.write_title(name)
        ws.write_data()
```

## 按列名指定数字格式

`write_data` 与 `write_summary` 的 `number_format` 参数支持字符串（应用到所有列）或字典（按列名指定）：

```python
ws.write_data(number_format={"金额": "#,##0.00", "比例": "0.00%"})
```

## 一次性覆盖

每个写入方法都接受 `style`/`border`/`height` 等关键字参数，传入即覆盖该次调用的主题样式，不修改主题本身：

```python
ws.write_data(body_style=CellStyle(font=Font(italic=True)))
```

## API 速览

`Sheet` 方法（写入前须先调用 `use(df)`）：

- `use(df, *, columns=None)` — 绑定 DataFrame（pandas 或 polars），可选重排列或选取列子集。
- `write_title(text, *, crossline=0, style=None, border=None, height=None)` — 写入跨列合并标题，`crossline` 控制跨行行数。
- `write_data(*, header_style=None, body_style=None, header_border=None, body_border=None, number_format=None, height=None)` — 写入表头与数据行。
- `write_summary(*, agg_cols=None, pass_cols=None, agg_fun="sum", row_name="总计", merge_cols=None, pass_seq="--", style=None, border=None, number_format=None, height=None)` — 写入合计行，`agg_cols` 求和、`pass_cols` 填占位符、`merge_cols` 合并前导列。
- `write_cell(range, value=None, *, style=None, height=None)` — 写入或合并写入任意单元格区域，`range` 支持 `"A1"` 或 `"A1:C3"`。
- `set_column_width(width, *, columns=None)` — 设置列宽，`columns` 省略则全部列，可传列名或列名列表。

`ExcelWriter` 方法：

- `ExcelWriter(filename, *, theme=None, start_row=1, start_col=1)` — 构造工作簿，可指定主题与写入起点。
- `.sheet(name=None, *, show_gridlines=False)` — 创建工作表，默认隐藏网格线。
- `.save()` — 保存文件；作为上下文管理器使用时退出即保存。

## 工具函数

`transColname2Letter(colnames, xlsDataRange)` 将列名映射到 Excel 列字母。传入列名列表与对应的 Excel 区域字符串（如 `"A1:D10"`），返回 `{列名: 列字母}` 字典。列名数量须与区域列数一致，否则抛出 `ValueError`。
