datraxlsx 0.3.0__py3-none-any.whl

datraxlsx/__init__.py

@@ -0,0 +1,4 @@
+from .styles import CellStyle, RowBorder, TableTheme
+from .writer import ExcelWriter, Sheet, transColname2Letter
+
+__all__ = ["CellStyle", "RowBorder", "TableTheme", "ExcelWriter", "Sheet", "transColname2Letter"]

datraxlsx/styles.py

@@ -0,0 +1,82 @@
+"""Reusable style objects for Excel writing."""
+from dataclasses import dataclass, replace
+
+from openpyxl.styles import Alignment, Border, Font, PatternFill, Side
+
+
+@dataclass(frozen=True)
+class CellStyle:
+    font: Font | None = None
+    fill: PatternFill | None = None
+    alignment: Alignment | None = None
+    border: Border | None = None
+    number_format: str | None = None
+
+    def apply(self, cell) -> None:
+        if self.font is not None:
+            cell.font = self.font
+        if self.fill is not None:
+            cell.fill = self.fill
+        if self.alignment is not None:
+            cell.alignment = self.alignment
+        if self.border is not None:
+            cell.border = self.border
+        if self.number_format is not None:
+            cell.number_format = self.number_format
+
+
+@dataclass(frozen=True)
+class RowBorder:
+    top: Side | None = None
+    bottom: Side | None = None
+    left_edge: Side | None = None
+    right_edge: Side | None = None
+    inner_vertical: Side | None = None
+
+    def apply_to_range(self, ws, start_col: int, start_row: int, end_col: int, end_row: int) -> None:
+        for r in range(start_row, end_row + 1):
+            for c in range(start_col, end_col + 1):
+                top = self.top if r == start_row else None
+                bottom = self.bottom if r == end_row else None
+                left = self.left_edge if c == start_col else self.inner_vertical
+                right = self.right_edge if c == end_col else self.inner_vertical
+                ws.cell(row=r, column=c).border = Border(top=top, bottom=bottom, left=left, right=right)
+
+
+@dataclass(frozen=True)
+class TableTheme:
+    title: CellStyle
+    header: CellStyle
+    body: CellStyle
+    summary: CellStyle
+    title_border: RowBorder | None = None
+    header_border: RowBorder | None = None
+    body_border: RowBorder | None = None
+    summary_border: RowBorder | None = None
+    title_height: int = 75
+    row_height: int = 33
+    column_width: float = 17.5
+
+    @classmethod
+    def default(cls) -> "TableTheme":
+        return cls(
+            title=CellStyle(
+                font=Font(name="微软雅黑", size=23, bold=True),
+                alignment=Alignment(horizontal="center", vertical="center"),
+            ),
+            header=CellStyle(
+                font=Font(name="微软雅黑", size=11.5, bold=True),
+                alignment=Alignment(horizontal="center", vertical="center", wrapText=True),
+            ),
+            body=CellStyle(
+                font=Font(name="微软雅黑", size=11.5),
+                alignment=Alignment(horizontal="center", vertical="center"),
+            ),
+            summary=CellStyle(
+                font=Font(name="微软雅黑", size=11.5, bold=True),
+                alignment=Alignment(horizontal="center", vertical="center"),
+            ),
+        )
+
+    def replace(self, **fields) -> "TableTheme":
+        return replace(self, **fields)

datraxlsx/writer.py

@@ -0,0 +1,271 @@
+"""DataFrame-to-Excel writer with style-based configuration."""
+from pathlib import Path
+
+import pandas as pd
+import polars as pl
+from openpyxl import Workbook
+from openpyxl.styles import Alignment, Border, Font, PatternFill, Side
+from openpyxl.utils.cell import cols_from_range, coordinate_from_string, get_column_letter
+from openpyxl.worksheet import cell_range
+from typing import Self
+
+from .styles import CellStyle, RowBorder, TableTheme
+
+# `range` is shadowed by the `write_cell` parameter; keep a builtin reference.
+_range = range
+
+
+def transColname2Letter(colnames: list[str], xlsDataRange: str) -> dict[str, str]:
+    colLetter = [i[0][0] for i in cols_from_range(xlsDataRange)]
+    if len(colnames) != len(colLetter):
+        raise ValueError("colnames must be equal to xlsDataRange")
+    return dict(zip(colnames, colLetter))
+
+
+class ExcelWriter:
+    def __init__(
+        self,
+        filename: str | Path,
+        *,
+        theme: TableTheme | None = None,
+        start_row: int = 1,
+        start_col: int = 1,
+    ) -> None:
+        self._filename = filename
+        self._wb = Workbook()
+        self._theme = theme or TableTheme.default()
+        self._start_row = start_row
+        self._start_col = start_col
+        self._first_sheet_used = False
+
+    def sheet(self, name: str | None = None, *, show_gridlines: bool = False) -> "Sheet":
+        if not self._first_sheet_used:
+            ws = self._wb.active
+            self._first_sheet_used = True
+        else:
+            ws = self._wb.create_sheet()
+        ws.sheet_view.showGridLines = show_gridlines
+        if name:
+            ws.title = name
+        return Sheet(ws, self._theme, self._start_row, self._start_col)
+
+    def save(self) -> None:
+        self._wb.save(self._filename)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        if exc_type is None:
+            self.save()
+
+
+class Sheet:
+    def __init__(self, ws, theme: TableTheme, start_row: int = 1, start_col: int = 1) -> None:
+        self._ws = ws
+        self._theme = theme
+        self._start_row = start_row
+        self._start_col = start_col
+        self._cursor = start_row
+        self._df = None
+        self._columns = None
+
+    def use(self, df, *, columns: list[str] | None = None) -> None:
+        if isinstance(df, pl.DataFrame):
+            df = df.to_pandas()
+        self._df = df
+        self._columns = columns if columns is not None else df.columns.tolist()
+
+    def _ncols(self) -> int:
+        return len(self._columns)
+
+    def write_title(
+        self,
+        text: str,
+        *,
+        crossline: int = 0,
+        style: CellStyle | None = None,
+        border: RowBorder | None = None,
+        height: int | None = None,
+    ) -> None:
+        if self._df is None:
+            raise ValueError("call use(df) before write_title()")
+        st = style or self._theme.title
+        bd = border if border is not None else self._theme.title_border
+        h = height if height is not None else self._theme.title_height
+        n = self._ncols()
+        start_row = self._cursor
+        end_row = start_row + crossline
+        start_cell = f"{get_column_letter(self._start_col)}{start_row}"
+        end_cell = f"{get_column_letter(self._start_col + n - 1)}{end_row}"
+        if end_cell != start_cell:
+            self._ws.merge_cells(f"{start_cell}:{end_cell}")
+        self._ws[start_cell].value = text
+        st.apply(self._ws[start_cell])
+        for r in range(start_row, end_row + 1):
+            self._ws.row_dimensions[r].height = h
+        if bd is not None:
+            bd.apply_to_range(self._ws, self._start_col, start_row, self._start_col + n - 1, end_row)
+        self._cursor = end_row + 1
+
+    def write_data(
+        self,
+        *,
+        header_style: CellStyle | None = None,
+        body_style: CellStyle | None = None,
+        header_border: RowBorder | None = None,
+        body_border: RowBorder | None = None,
+        number_format: str | dict | None = None,
+        height: int | None = None,
+    ) -> None:
+        if self._df is None:
+            raise ValueError("call use(df) before write_data()")
+        hs = header_style or self._theme.header
+        bs = body_style or self._theme.body
+        hb = header_border if header_border is not None else self._theme.header_border
+        bb = body_border if body_border is not None else self._theme.body_border
+        h = height if height is not None else self._theme.row_height
+        n = self._ncols()
+        df = self._df[self._columns]
+
+        hr = self._cursor
+        for j, col in enumerate(self._columns):
+            cell = self._ws.cell(row=hr, column=self._start_col + j, value=col)
+            hs.apply(cell)
+        self._ws.row_dimensions[hr].height = h
+        if hb is not None:
+            hb.apply_to_range(self._ws, self._start_col, hr, self._start_col + n - 1, hr)
+        self._cursor = hr + 1
+
+        for row_values in df.to_numpy().tolist():
+            r = self._cursor
+            for j, val in enumerate(row_values):
+                cell = self._ws.cell(row=r, column=self._start_col + j, value=val)
+                bs.apply(cell)
+            self._ws.row_dimensions[r].height = h
+            if bb is not None:
+                bb.apply_to_range(self._ws, self._start_col, r, self._start_col + n - 1, r)
+            self._cursor = r + 1
+
+        if number_format is not None:
+            self._apply_number_format(number_format, hr + 1, self._cursor - 1)
+
+    def write_summary(
+        self,
+        *,
+        agg_cols: list[str] | None = None,
+        pass_cols: list[str] | None = None,
+        agg_fun: str = "sum",
+        row_name: str = "总计",
+        merge_cols: list[str] | None = None,
+        pass_seq: str = "--",
+        style: CellStyle | None = None,
+        border: RowBorder | None = None,
+        number_format: str | dict | None = None,
+        height: int | None = None,
+    ) -> None:
+        if self._df is None:
+            raise ValueError("call use(df) before write_summary()")
+        st = style or self._theme.summary
+        bd = border if border is not None else self._theme.summary_border
+        h = height if height is not None else self._theme.row_height
+        n = self._ncols()
+        df = self._df[self._columns]
+        if merge_cols:
+            if merge_cols != self._columns[: len(merge_cols)]:
+                raise ValueError("merge_cols must be the leading columns")
+            nm = len(merge_cols)
+        else:
+            nm = 0
+
+        values = [row_name] * nm
+        for col in self._columns[nm:]:
+            if agg_cols and col in agg_cols:
+                values.append(df[col].agg(agg_fun))
+            elif pass_cols and col in pass_cols:
+                values.append(pass_seq)
+            elif pd.api.types.is_numeric_dtype(df[col].dtype):
+                values.append(df[col].agg(agg_fun))
+            else:
+                values.append(df[col].iloc[0])
+
+        r = self._cursor
+        for j, val in enumerate(values):
+            cell = self._ws.cell(row=r, column=self._start_col + j, value=val)
+            st.apply(cell)
+        if nm > 0:
+            sc = f"{get_column_letter(self._start_col)}{r}"
+            ec = f"{get_column_letter(self._start_col + nm - 1)}{r}"
+            if ec != sc:
+                self._ws.merge_cells(f"{sc}:{ec}")
+            self._ws[sc].value = row_name
+            st.apply(self._ws[sc])
+        self._ws.row_dimensions[r].height = h
+        if bd is not None:
+            bd.apply_to_range(self._ws, self._start_col, r, self._start_col + n - 1, r)
+        self._cursor = r + 1
+        if number_format is not None:
+            self._apply_number_format(number_format, r, r)
+
+    def write_cell(
+        self,
+        range: str,
+        value=None,
+        *,
+        style: CellStyle | None = None,
+        height: int | None = None,
+    ) -> None:
+        h = height if height is not None else self._theme.row_height
+        if ":" in range:
+            self._ws.merge_cells(range)
+            top_left = range.split(":")[0]
+            cell = self._ws[top_left]
+            if value is not None:
+                cell.value = value
+            if style is not None:
+                style.apply(cell)
+            bounds = cell_range.CellRange(range_string=range).bounds
+            for r in _range(bounds[1], bounds[3] + 1):
+                self._ws.row_dimensions[r].height = h
+        else:
+            cell = self._ws[range]
+            if value is not None:
+                cell.value = value
+            if style is not None:
+                style.apply(cell)
+            bounds = cell_range.CellRange(range_string=range).bounds
+            self._ws.row_dimensions[bounds[1]].height = h
+
+    def set_column_width(self, width: float, *, columns: str | list[str] | None = None) -> None:
+        if self._df is None:
+            raise ValueError("call use(df) before set_column_width()")
+        if columns is None:
+            for j in range(self._ncols()):
+                self._ws.column_dimensions[get_column_letter(self._start_col + j)].width = width
+        elif isinstance(columns, str):
+            if columns in self._columns:
+                j = self._columns.index(columns)
+                letter = get_column_letter(self._start_col + j)
+            else:
+                letter = columns
+            self._ws.column_dimensions[letter].width = width
+        else:
+            for c in columns:
+                j = self._columns.index(c)
+                self._ws.column_dimensions[get_column_letter(self._start_col + j)].width = width
+
+    def _apply_number_format(self, number_format, first_row: int, last_row: int) -> None:
+        if isinstance(number_format, str):
+            for r in range(first_row, last_row + 1):
+                for j in range(self._ncols()):
+                    self._ws.cell(row=r, column=self._start_col + j).number_format = number_format
+        elif isinstance(number_format, dict):
+            col_to_idx = {name: i for i, name in enumerate(self._columns)}
+            for name, fmt in number_format.items():
+                if name not in col_to_idx:
+                    raise KeyError(name)
+                j = col_to_idx[name]
+                for r in range(first_row, last_row + 1):
+                    self._ws.cell(row=r, column=self._start_col + j).number_format = fmt
+        else:
+            raise TypeError("number_format must be str or dict")

datraxlsx-0.3.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+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`。

datraxlsx-0.3.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+datraxlsx/__init__.py,sha256=SEsBJsXct6zZ_6cKbqs3bOB6xjerKMXOdyi42MDxUco,212
+datraxlsx/styles.py,sha256=7bdj4V5Cy5CnojgpnCuUVvHCkwDPufeIpDdXEpT3So0,2932
+datraxlsx/writer.py,sha256=7eLde5e0AX164h1ifH-94xYrmd0JqS9Vsa2ZKfeAyrY,10737
+datraxlsx-0.3.0.dist-info/WHEEL,sha256=uOqnPWqgFlbov4NeTCercq7cBQ2UN7xh5fiW55lOnAg,81
+datraxlsx-0.3.0.dist-info/METADATA,sha256=2swSbub_y796tVl52AfAC-jE_kzNkDT8SMY9IHeMzCs,5243
+datraxlsx-0.3.0.dist-info/RECORD,,

datraxlsx-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.26
+Root-Is-Purelib: true
+Tag: py3-none-any