tesorotools-python 0.0.40__tar.gz → 0.0.41__tar.gz

{tesorotools_python-0.0.40 → tesorotools_python-0.0.41}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesorotools-python
-Version: 0.0.40
+Version: 0.0.41
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: matplotlib>=3.10

{tesorotools_python-0.0.40 → tesorotools_python-0.0.41}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "tesorotools-python"
 requires-python = ">=3.13"
-version = "0.0.40"
+version = "0.0.41"
 dependencies = [
     # database and ORM
     "psycopg[binary]>=3.1",

{tesorotools_python-0.0.40 → tesorotools_python-0.0.41}/src/tesorotools/assets/plots.yaml

@@ -39,3 +39,6 @@ line:
 table:
   style: Light Shading Accent 1
   autofit: False
+  block_separator:
+    fill: "BFBFBF"      # hex color of the inter-block band
+    height_twips: 20    # half-band height; total band = 2 * height_twips

{tesorotools_python-0.0.40 → tesorotools_python-0.0.41}/src/tesorotools/render/content/table.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 # pyright: reportPrivateUsage=false
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Self
+from typing import Any, Self, TypedDict
 
 import numpy as np
 import pandas as pd
@@ -25,6 +25,35 @@ from tesorotools.utils.template import TemplateLoader
 RENDER_CONFIG: dict[str, Any] = read_config(PLOT_CONFIG_FILE)["table"]
 
 
+class BlockSeparatorConfig(TypedDict, total=False):
+    """User-facing visual config for the inter-block separator band.
+
+    The band is rendered as **two adjacent rows** sharing the same
+    fill, so the pair shifts Word's automatic banding count by an
+    even number (preserving alternation in data rows below). Both
+    keys are optional; missing keys fall back to defaults.
+    """
+
+    fill: str
+    """Hex color of the band, without leading ``#``. Default ``BFBFBF``."""
+
+    height_twips: int
+    """Height of *each* of the two rows. Total band height is
+    ``2 * height_twips``. Default ``20`` (1pt per row, 2pt total)."""
+
+
+class _ResolvedSeparator(TypedDict):
+    """Internal, fully-resolved variant of :class:`BlockSeparatorConfig`.
+
+    After defaults are merged in, every field is guaranteed present —
+    this lets call sites index without ``.get()`` and silences
+    pyright's NotRequired warnings.
+    """
+
+    fill: str
+    height_twips: int
+
+
 @dataclass(frozen=True)
 class RenderConfig:
     """Per-call rendering options for :func:`render_table`.
@@ -36,12 +65,18 @@ class RenderConfig:
 
     style: str | None = None
     autofit: bool = False
+    block_separator: BlockSeparatorConfig | None = None
 
     @classmethod
     def from_global(cls) -> RenderConfig:
+        sep_raw: Any = RENDER_CONFIG.get("block_separator")
+        block_separator: BlockSeparatorConfig | None = (
+            None if sep_raw is None else BlockSeparatorConfig(**sep_raw)
+        )
         return cls(
             style=RENDER_CONFIG.get("style"),
             autofit=bool(RENDER_CONFIG["autofit"]),
+            block_separator=block_separator,
         )
 
 
@@ -142,58 +177,125 @@ def _fill_index_names(
         _style_index_names(cell)
 
 
+_DEFAULT_SEPARATOR: _ResolvedSeparator = {
+    "fill": "BFBFBF",
+    "height_twips": 20,
+}
+
+
 # we only separate blocks in vertically stacked tables
 def _separate_blocks(
     index: pd.Index[Any] | pd.MultiIndex,
     table_docx: TableDocx,
+    *,
+    horizontal: bool,
+    config: BlockSeparatorConfig | None = None,
 ) -> None:
+    """Insert two adjacent separator rows after every block boundary.
+
+    Each separator is one merged cell (``<w:gridSpan>`` covering all
+    columns) with exact-height ``<w:trHeight>`` and a solid ``<w:shd>``
+    fill. Two adjacent rows with identical fill render as a single
+    seamless band; their pair shifts Word's automatic banding count by
+    an even number, preserving the alternation in the data rows below.
+
+    The cnfStyle approach this replaces was OOXML-valid but Word
+    treated ``<w:cnfStyle>`` as descriptive bookkeeping rather than as
+    an override directive — the conditional formatting was never
+    applied. See README "Block separators" for the postmortem.
+    """
     if not isinstance(index, pd.MultiIndex):
         raise ValueError(
             "block_sep=True requires the row index to be a MultiIndex; "
             "got a flat Index. Set block_sep=False or wrap rows in a "
             "MultiIndex with the block name as level 0."
         )
-    _disable_implicit_last_row(table_docx)
+    cfg: _ResolvedSeparator = {**_DEFAULT_SEPARATOR, **(config or {})}
+    num_cols: int = len(table_docx.columns)
+    grid_total: int = _grid_total_twips(table_docx)
+    header_rows: int = 2 if horizontal else 1
     blocks: list[str] = list(index.get_level_values(level=0).unique())
     previous_rows: int = 0
+    inserted: int = 0
     for block in blocks[:-1]:
         block_size: int = len(index[index.get_level_values(level=0) == block])
-        _separate_row(table_docx.rows[block_size + previous_rows])
+        anchor_idx: int = (
+            header_rows + previous_rows + block_size - 1 + inserted
+        )
+        anchor: TableRow = table_docx.rows[anchor_idx]
+        _insert_double_separator(anchor, num_cols, grid_total, cfg)
         previous_rows += block_size
+        inserted += 2
 
 
-def _separate_row(row: TableRow) -> None:
-    """Mark *row* as ``lastRow`` via conditional-formatting reference.
-
-    The visible separator border belongs to the active table style
-    (``<w:tblStylePr w:type="lastRow">`` in ``styles.xml``). Emitting
-    only ``<w:cnfStyle>`` on ``<w:trPr>`` keeps direct formatting out of
-    ``<w:tcPr>``, which is the construct Word's co-authoring merge
-    engine corrupts in shared OneDrive/SharePoint documents. The
-    consumer's ``template.docx`` must define the ``lastRow`` conditional
-    formatting on the table style referenced by ``plots.yaml``.
-    """
-    trPr: Any = row._tr.get_or_add_trPr()  # type: ignore[reportUnknownMemberType]
-    cnfStyle: Any = OxmlElement("w:cnfStyle")  # type: ignore[reportUnknownVariableType]
-    # 12-bit mask, ECMA-376 §17.4.7. Bit 1 (zero-indexed) = lastRow.
-    cnfStyle.set(qn("w:val"), "010000000000")  # type: ignore[reportUnknownMemberType]
-    trPr.append(cnfStyle)  # type: ignore[reportUnknownMemberType]
-
+def _grid_total_twips(table_docx: TableDocx) -> int:
+    """Sum the widths of every ``<w:gridCol>`` under ``<w:tblGrid>``."""
+    tblGrid: Any = table_docx._element.find(qn("w:tblGrid"))  # type: ignore[reportUnknownMemberType]
+    cols: Any = tblGrid.findall(qn("w:gridCol"))  # type: ignore[reportUnknownMemberType]
+    return sum(int(gc.get(qn("w:w"))) for gc in cols)  # type: ignore[reportUnknownArgumentType, reportUnknownVariableType]
 
-def _disable_implicit_last_row(table_docx: TableDocx) -> None:
-    """Force ``<w:tblLook w:lastRow="0"/>`` so the real last row stays plain.
 
-    With block_sep we mark *interior* rows as ``lastRow`` via
-    ``cnfStyle``. The table's own last row must not pick up the same
-    conditional formatting automatically, so we disable the implicit
-    ``lastRow`` flag at the ``<w:tblLook>`` level.
-    """
-    tblPr: Any = table_docx._element.tblPr  # type: ignore[reportUnknownMemberType]
-    tblLook: Any = tblPr.find(qn("w:tblLook"))  # type: ignore[reportUnknownMemberType]
-    if tblLook is None:
-        tblLook = OxmlElement("w:tblLook")  # type: ignore[reportUnknownVariableType]
-        tblPr.append(tblLook)  # type: ignore[reportUnknownMemberType]
-    tblLook.set(qn("w:lastRow"), "0")  # type: ignore[reportUnknownMemberType]
+def _insert_double_separator(
+    anchor_row: TableRow,
+    num_cols: int,
+    grid_total_twips: int,
+    cfg: _ResolvedSeparator,
+) -> None:
+    sep1: Any = _build_separator_row(num_cols, grid_total_twips, cfg)
+    sep2: Any = _build_separator_row(num_cols, grid_total_twips, cfg)
+    # Insert sep2 first, then sep1 in front of sep2 — both end up after
+    # anchor_row in document order (anchor → sep1 → sep2 → next data row).
+    anchor_row._tr.addnext(sep2)  # type: ignore[reportUnknownMemberType]
+    anchor_row._tr.addnext(sep1)  # type: ignore[reportUnknownMemberType]
+
+
+def _build_separator_row(
+    num_cols: int, grid_total_twips: int, cfg: _ResolvedSeparator
+) -> Any:
+    fill: str = cfg["fill"]
+    height_twips: int = cfg["height_twips"]
+
+    tr: Any = OxmlElement("w:tr")  # type: ignore[reportUnknownVariableType]
+
+    trPr: Any = OxmlElement("w:trPr")  # type: ignore[reportUnknownVariableType]
+    trHeight: Any = OxmlElement("w:trHeight")  # type: ignore[reportUnknownVariableType]
+    trHeight.set(qn("w:val"), str(height_twips))  # type: ignore[reportUnknownMemberType]
+    trHeight.set(qn("w:hRule"), "exact")  # type: ignore[reportUnknownMemberType]
+    trPr.append(trHeight)  # type: ignore[reportUnknownMemberType]
+    tr.append(trPr)  # type: ignore[reportUnknownMemberType]
+
+    tc: Any = OxmlElement("w:tc")  # type: ignore[reportUnknownVariableType]
+    tcPr: Any = OxmlElement("w:tcPr")  # type: ignore[reportUnknownVariableType]
+    tcW: Any = OxmlElement("w:tcW")  # type: ignore[reportUnknownVariableType]
+    tcW.set(qn("w:w"), str(grid_total_twips))  # type: ignore[reportUnknownMemberType]
+    tcW.set(qn("w:type"), "dxa")  # type: ignore[reportUnknownMemberType]
+    tcPr.append(tcW)  # type: ignore[reportUnknownMemberType]
+    gridSpan: Any = OxmlElement("w:gridSpan")  # type: ignore[reportUnknownVariableType]
+    gridSpan.set(qn("w:val"), str(num_cols))  # type: ignore[reportUnknownMemberType]
+    tcPr.append(gridSpan)  # type: ignore[reportUnknownMemberType]
+    shd: Any = OxmlElement("w:shd")  # type: ignore[reportUnknownVariableType]
+    shd.set(qn("w:val"), "clear")  # type: ignore[reportUnknownMemberType]
+    shd.set(qn("w:color"), "auto")  # type: ignore[reportUnknownMemberType]
+    shd.set(qn("w:fill"), fill)  # type: ignore[reportUnknownMemberType]
+    tcPr.append(shd)  # type: ignore[reportUnknownMemberType]
+    tc.append(tcPr)  # type: ignore[reportUnknownMemberType]
+
+    # OOXML requires <w:tc> to contain at least one block-level element.
+    # The inner paragraph carries exact line spacing so Word does not
+    # inflate the row past the configured trHeight on screen.
+    p: Any = OxmlElement("w:p")  # type: ignore[reportUnknownVariableType]
+    pPr: Any = OxmlElement("w:pPr")  # type: ignore[reportUnknownVariableType]
+    spacing: Any = OxmlElement("w:spacing")  # type: ignore[reportUnknownVariableType]
+    spacing.set(qn("w:before"), "0")  # type: ignore[reportUnknownMemberType]
+    spacing.set(qn("w:after"), "0")  # type: ignore[reportUnknownMemberType]
+    spacing.set(qn("w:line"), str(height_twips))  # type: ignore[reportUnknownMemberType]
+    spacing.set(qn("w:lineRule"), "exact")  # type: ignore[reportUnknownMemberType]
+    pPr.append(spacing)  # type: ignore[reportUnknownMemberType]
+    p.append(pPr)  # type: ignore[reportUnknownMemberType]
+    tc.append(p)  # type: ignore[reportUnknownMemberType]
+
+    tr.append(tc)  # type: ignore[reportUnknownMemberType]
+    return tr  # type: ignore[reportUnknownVariableType]
 
 
 def _is_bright(hex_color: str) -> bool:
@@ -296,9 +398,17 @@ def render_table(
         horizontal=horizontal,
         **kwargs,
     )
-    if block_sep:
-        _separate_blocks(table.index, table_docx)
     _fill_content(table, color_table, shade_table, table_docx, horizontal)
+    # Block separators insert *new rows* into the table, so they must
+    # run after _fill_content — otherwise the (row, col) indexing in
+    # _fill_content would land on the inserted separator rows.
+    if block_sep:
+        _separate_blocks(
+            table.index,
+            table_docx,
+            horizontal=horizontal,
+            config=cfg.block_separator,
+        )
     table_docx.alignment = WD_TABLE_ALIGNMENT.CENTER
     return table_docx