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

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

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

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

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

{tesorotools_python-0.0.39 → 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.39 → 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
@@ -15,6 +15,7 @@ from docx.oxml.ns import nsdecls, qn
 from docx.shared import Inches, Pt, RGBColor
 from docx.table import Table as TableDocx
 from docx.table import _Cell as TableCell
+from docx.table import _Row as TableRow
 from yaml import MappingNode
 
 from tesorotools.utils.config import read_config
@@ -24,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`.
@@ -35,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,
         )
 
 
@@ -49,46 +85,6 @@ TEXTO_TABLAS: int = 9
 CENTER = WD_ALIGN_PARAGRAPH.CENTER
 
 
-def _set_cell_border(cell: TableCell, **kwargs: Any) -> None:
-    """
-    Set cell`s border
-    Usage:
-
-    set_cell_border(
-        cell,
-        top={"sz": 12, "val": "single", "color": "#FF0000", "space": "0"},
-        bottom={"sz": 12, "color": "#00FF00", "val": "single"},
-        start={"sz": 24, "val": "dashed", "shadow": "true"},
-        end={"sz": 12, "val": "dashed"},
-    )
-    """
-    tc = cell._tc
-    tcPr = tc.get_or_add_tcPr()
-
-    # check for tag existence, if none found, create one
-    tcBorders: Any = tcPr.first_child_found_in("w:tcBorders")  # type: ignore[reportUnknownMemberType]
-    if tcBorders is None:
-        tcBorders = OxmlElement("w:tcBorders")  # type: ignore[reportUnknownVariableType]
-        tcPr.append(tcBorders)  # type: ignore[reportUnknownMemberType]
-
-    # list over all available tags
-    for edge in ("start", "top", "end", "bottom", "insideH", "insideV"):
-        edge_data: Any = kwargs.get(edge)
-        if edge_data:
-            tag = "w:{}".format(edge)
-
-            # check for tag existence, if none found, then create one
-            element: Any = tcBorders.find(qn(tag))  # type: ignore[reportUnknownMemberType]
-            if element is None:
-                element = OxmlElement(tag)  # type: ignore[reportUnknownVariableType]
-                tcBorders.append(element)  # type: ignore[reportUnknownMemberType]
-
-            # looks like order of attributes is important
-            for key in ["sz", "val", "color", "space", "shadow"]:
-                if key in edge_data:
-                    element.set(qn("w:{}".format(key)), str(edge_data[key]))  # type: ignore[reportUnknownMemberType]
-
-
 def _style_horizontal_blocks_header(cell: TableCell) -> None:
     cell.paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.CENTER
     cell.paragraphs[0].runs[0].font.size = Pt(12)
@@ -181,36 +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."
         )
+    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])
-        for cell in table_docx.rows[block_size + previous_rows].cells:
-            _separate_cell(cell)
+        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_cell(cell: TableCell) -> None:
-    _set_cell_border(
-        cell,
-        bottom={
-            "sz": 1,
-            "val": "double",
-            "color": "#000000",
-            "space": 2,
-        },
-    )
+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 _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:
@@ -313,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