tytable 0.6.0__py3-none-any.whl

tytable/_format.py

@@ -0,0 +1,282 @@
+"""
+Value formatting: digits, significant figures, replace, escape, and fn transforms.
+
+Applied during the render pipeline by :func:`tytable._resolve.build`.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING, Any
+
+from ._escape import escape_typst
+from ._indices import resolve_i, resolve_j
+
+if TYPE_CHECKING:
+    from ._directives import FormatDirective
+    from ._tytable import TinyTable
+
+Cell = tuple[int, int]
+
+
+def _is_numeric_typed(val: object) -> bool:
+    """True for ints/floats but not bools (which are technically int subclasses)."""
+    if isinstance(val, bool):
+        return False
+    return isinstance(val, (int, float))
+
+
+def _fmt_numeric_decimal(val: Any, digits: int) -> str:
+    """Format a number with a fixed number of decimal places."""
+    return f"{float(val):.{digits}f}"
+
+
+def _fmt_numeric_significant(val: Any, digits: int) -> str:
+    """Format a number to a given number of significant figures."""
+    return f"{float(val):.{digits}g}"
+
+
+def _matches(o: object, typed: object, s: str) -> bool:
+    """Check whether a ``replace`` key matches a typed value or its string form (handles null/nan/inf)."""
+    if o is None:
+        return typed is None
+    if isinstance(o, float) and math.isnan(o):
+        return isinstance(typed, float) and math.isnan(typed)
+    if isinstance(o, float) and math.isinf(o):
+        return isinstance(typed, float) and math.isinf(typed) and (typed > 0) == (o > 0)
+    if isinstance(o, str):
+        lo = o.lower()
+        if lo == "null":
+            return typed is None
+        if lo == "nan":
+            return isinstance(typed, float) and math.isnan(typed)
+        if lo == "inf":
+            return isinstance(typed, float) and math.isinf(typed) and typed > 0
+        if lo == "-inf":
+            return isinstance(typed, float) and math.isinf(typed) and typed < 0
+    return typed == o or s == str(o)
+
+
+def _apply_replace(typed_val: object, current_str: str, replace: object) -> str:
+    """Apply a ``replace`` spec (``True``, a fill string, or an ``{old: new}`` dict) to one cell."""
+    if replace is True:
+        if typed_val is None or (isinstance(typed_val, float) and math.isnan(typed_val)):
+            return " "
+        return current_str
+    if isinstance(replace, str):
+        if typed_val is None or (isinstance(typed_val, float) and math.isnan(typed_val)):
+            return replace
+        return current_str
+    if isinstance(replace, dict):
+        mapping: dict = {}
+        for k, v in replace.items():
+            if isinstance(k, list):
+                for item in k:
+                    mapping[item] = v
+            else:
+                mapping[k] = v
+        for old, new in mapping.items():
+            if _matches(old, typed_val, current_str):
+                return str(new)
+    return current_str
+
+
+def _apply_escape(current_str: str, escape_spec: object, output: str) -> str:
+    """Re-escape a cell string for the target backend when ``fmt(escape=...)`` is set."""
+    if escape_spec is True or escape_spec == "typst":
+        if output in ("html", "ascii"):
+            from ._escape import escape_html
+
+            return escape_html(current_str)
+        return escape_typst(current_str)
+    return current_str
+
+
+def _resolve_target_cells(
+    i_vals: list[int],
+    j_vals: list[int],
+    data_body: list[list[str]],
+    colnames_display: list[str],
+) -> list[Cell]:
+    """Translate resolved table coordinates into body/header cell coordinates."""
+    target_cells: list[Cell] = []
+    for i_idx in i_vals:
+        if i_idx == 0:
+            target_cells.extend(
+                (-1, j_idx - 1) for j_idx in j_vals if 0 < j_idx <= len(colnames_display)
+            )
+            continue
+        row_idx = i_idx - 1
+        if row_idx < 0 or row_idx >= len(data_body):
+            continue
+        target_cells.extend(
+            (row_idx, j_idx - 1) for j_idx in j_vals if 0 < j_idx <= len(data_body[row_idx])
+        )
+    return target_cells
+
+
+def _typed_value(cell: Cell, typed_body: list[list[Any]], colnames: list[str]) -> object | None:
+    """Return the original typed value for a body or header cell."""
+    row_idx, col_idx = cell
+    if row_idx == -1:
+        return colnames[col_idx]
+    if row_idx < len(typed_body) and col_idx < len(typed_body[row_idx]):
+        return typed_body[row_idx][col_idx]
+    return None
+
+
+def _cell_value(cell: Cell, data_body: list[list[str]], colnames_display: list[str]) -> str:
+    """Read the current rendered value of a body or header cell."""
+    row_idx, col_idx = cell
+    return colnames_display[col_idx] if row_idx == -1 else data_body[row_idx][col_idx]
+
+
+def _set_cell_value(
+    cell: Cell,
+    value: object,
+    data_body: list[list[str]],
+    colnames_display: list[str],
+) -> None:
+    """Set the rendered value of a body or header cell."""
+    row_idx, col_idx = cell
+    if row_idx == -1:
+        colnames_display[col_idx] = str(value)
+    else:
+        data_body[row_idx][col_idx] = str(value)
+
+
+def _apply_digits(
+    cells: list[Cell],
+    directive: FormatDirective,
+    data_body: list[list[str]],
+    typed_body: list[list[Any]],
+    colnames_display: list[str],
+    colnames: list[str],
+) -> None:
+    """Apply numeric formatting to the selected cells."""
+    if directive.digits is None:
+        return
+    formatter = (
+        _fmt_numeric_significant if directive.num_fmt == "significant" else _fmt_numeric_decimal
+    )
+    for cell in cells:
+        typed_val = _typed_value(cell, typed_body, colnames)
+        if _is_numeric_typed(typed_val) and not isinstance(typed_val, int):
+            _set_cell_value(
+                cell, formatter(typed_val, directive.digits), data_body, colnames_display
+            )
+
+
+def _apply_fn(
+    cells: list[Cell],
+    directive: FormatDirective,
+    data_body: list[list[str]],
+    colnames_display: list[str],
+) -> None:
+    """Apply a column-wise transform to the selected cells."""
+    if directive.fn is None:
+        return
+    col_to_rows: dict[int, list[int]] = {}
+    for row_idx, col_idx in cells:
+        col_to_rows.setdefault(col_idx, []).append(row_idx)
+    for col_idx, rows in col_to_rows.items():
+        column_cells = [(row_idx, col_idx) for row_idx in sorted(rows)]
+        values = [_cell_value(cell, data_body, colnames_display) for cell in column_cells]
+        result = directive.fn(values)
+        if len(result) != len(values):
+            raise ValueError(f"fn() returned {len(result)} items, expected {len(values)}")
+        for cell, value in zip(column_cells, result, strict=True):
+            _set_cell_value(cell, value, data_body, colnames_display)
+
+
+def _apply_replacements(
+    cells: list[Cell],
+    directive: FormatDirective,
+    data_body: list[list[str]],
+    typed_body: list[list[Any]],
+    colnames_display: list[str],
+    colnames: list[str],
+) -> None:
+    """Apply replacement rules to the selected cells."""
+    if directive.replace is None:
+        return
+    for cell in cells:
+        formatted = _apply_replace(
+            _typed_value(cell, typed_body, colnames),
+            _cell_value(cell, data_body, colnames_display),
+            directive.replace,
+        )
+        _set_cell_value(cell, formatted, data_body, colnames_display)
+
+
+def _apply_escapes(
+    cells: list[Cell],
+    directive: FormatDirective,
+    data_body: list[list[str]],
+    colnames_display: list[str],
+    output: str,
+) -> set[Cell]:
+    """Apply directive-level escaping and return the escaped cell coordinates."""
+    if not directive.escape:
+        return set()
+    for cell in cells:
+        formatted = _apply_escape(
+            _cell_value(cell, data_body, colnames_display), directive.escape, output
+        )
+        _set_cell_value(cell, formatted, data_body, colnames_display)
+    return set(cells)
+
+
+def apply_formats(
+    data_body: list[list[str]],
+    typed_body: list[list[Any]],
+    colnames_display: list[str],
+    table: TinyTable,
+    *,
+    nhead: int,
+    has_header: bool,
+    n_merged_body: int,
+    group_positions: set[int],
+    output: str,
+    colnames: list[str],
+) -> set[tuple[int, int]]:
+    """Apply every ``FormatDirective``, returning cells that were explicitly escaped.
+
+    Body cells use their zero-based row index.  Header cells use row ``-1`` so
+    callers can distinguish them when applying the table-wide escape pass.
+    """
+    escaped_cells: set[tuple[int, int]] = set()
+
+    for d in table._format_directives:
+        if d.output is not None and output not in d.output:
+            continue
+
+        i_vals = resolve_i(
+            d.i,
+            nhead=nhead,
+            group_positions=group_positions,
+            n_merged_body=n_merged_body,
+            has_header=has_header,
+            data=table._data,
+        )
+        if i_vals is None:
+            i_vals = resolve_i(
+                "body",
+                nhead=nhead,
+                group_positions=group_positions,
+                n_merged_body=n_merged_body,
+                has_header=has_header,
+            )
+        if i_vals is None:
+            raise RuntimeError("i_vals unexpectedly None in apply_formats")
+        j_vals = resolve_j(d.j, colnames, regex=d.regex)
+
+        target_cells = _resolve_target_cells(i_vals, j_vals, data_body, colnames_display)
+        _apply_digits(target_cells, d, data_body, typed_body, colnames_display, table._colnames)
+        _apply_fn(target_cells, d, data_body, colnames_display)
+        _apply_replacements(
+            target_cells, d, data_body, typed_body, colnames_display, table._colnames
+        )
+        escaped_cells.update(_apply_escapes(target_cells, d, data_body, colnames_display, output))
+
+    return escaped_cells

tytable/_groups.py

@@ -0,0 +1,158 @@
+"""
+Row and column group registration and merging into the table body.
+
+Called by :meth:`TinyTable.group` to record groups, and by
+:func:`tytable._resolve.build` to merge row-group separator rows into the body.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ._directives import RowGroup
+
+if TYPE_CHECKING:
+    from ._tytable import TinyTable
+
+
+def _resolve_cols(col_spec: list[str | int], colnames: list[str]) -> list[int]:
+    """Translate a list of column names/positions into 0-based integer indices."""
+    indices = []
+    for c in col_spec:
+        if isinstance(c, str):
+            try:
+                indices.append(colnames.index(c))
+            except ValueError:
+                raise ValueError(f"column {c!r} not found") from None
+        elif isinstance(c, int):
+            indices.append(c)
+        else:
+            raise TypeError(f"column spec must be str or int, got {type(c).__name__}")
+    return indices
+
+
+def _build_col_group_row(
+    j_dict: dict[str, list[str | int]], colnames: list[str]
+) -> list[str | None]:
+    """Build one column-group header row (label at span start, ``""`` under the span, ``None`` elsewhere)."""
+    ncol = len(colnames)
+    row: list[str | None] = [None] * ncol
+    for label, cols in j_dict.items():
+        indices = _resolve_cols(cols, colnames)
+        if not indices:
+            continue
+        start = indices[0]
+        row[start] = label
+        for ci in indices[1:]:
+            if 0 <= ci < ncol:
+                row[ci] = ""
+    return row
+
+
+def _build_col_group_rows_delim(delim: str, colnames: list[str]) -> list[list[str | None]]:
+    """Split column names on ``delim`` and build one header row per hierarchical level."""
+    parts = [c.split(delim) for c in colnames]
+    nlevels = len(parts[0])
+    if any(len(p) != nlevels for p in parts):
+        raise ValueError(
+            f"delimiter {delim!r} does not split all column names into the same number of parts"
+        )
+    rows: list[list[str | None]] = []
+    for level in range(nlevels):
+        ncol = len(colnames)
+        row: list[str | None] = [None] * ncol
+        i = 0
+        while i < ncol:
+            label = parts[i][level].strip()
+            start = i
+            i += 1
+            while i < ncol and parts[i][level].strip() == label:
+                i += 1
+            display = label if label else " "
+            row[start] = display
+            for ci in range(start + 1, i):
+                row[ci] = ""
+        rows.append(row)
+    return rows
+
+
+def _resolve_col_group_spans(row: list[str | None]) -> list[tuple[str, int, int]]:
+    """Return ``(label, start, span)`` entries for a column-group header row.
+
+    An empty string immediately after a label extends that label's span, while
+    ``None`` and standalone empty strings each represent one blank cell.
+    """
+    spans: list[tuple[str, int, int]] = []
+    i = 0
+    while i < len(row):
+        value = row[i]
+        label = "" if value is None else value.strip()
+        start = i
+        i += 1
+        if label:
+            while i < len(row) and row[i] is not None and (row[i] or "").strip() == "":
+                i += 1
+        spans.append((label, start, i - start))
+    return spans
+
+
+def register_row_groups(table: TinyTable, i: dict[str, int] | list[Any]) -> TinyTable:
+    """Record row-group separators from a ``{label: row}`` dict or a run-length list."""
+    if isinstance(i, dict):
+        pairs = sorted(i.items(), key=lambda x: x[1])
+        for label, pos in pairs:
+            table._row_groups.append(RowGroup(label=str(label), position=int(pos)))
+    elif isinstance(i, list):
+        prev = None
+        pos = 0
+        for idx, val in enumerate(i):
+            if idx > 0 and val != prev:
+                table._row_groups.append(RowGroup(label=str(prev), position=pos))
+                pos = idx
+            prev = val
+        if pos < len(i) and prev is not None:
+            table._row_groups.append(RowGroup(label=str(prev), position=pos))
+    else:
+        raise TypeError("group(i=...) must be a dict or list")
+    return table
+
+
+def register_col_groups(
+    table: TinyTable, j: dict[str, list[str | int]] | str, colnames: list[str]
+) -> TinyTable:
+    """Record column-group header rows from a ``{label: [cols]}`` dict or a delimiter string."""
+    if isinstance(j, dict):
+        row = _build_col_group_row(j, colnames)
+        table._col_group_rows.insert(0, row)
+    elif isinstance(j, str):
+        rows = _build_col_group_rows_delim(j, colnames)
+        for row in reversed(rows):
+            table._col_group_rows.insert(0, row)
+    else:
+        raise TypeError("group(j=...) must be a dict or str")
+    return table
+
+
+def merge_row_groups(
+    data_body: list[list[str]], row_groups: list[RowGroup], ncols: int
+) -> tuple[list[list[str]], dict[int, str]]:
+    """Interleave row-group separator rows into the body; returns the merged body and ``{row: label}``."""
+    if not row_groups:
+        return data_body, {}
+    nrows = len(data_body)
+    ngroups = len(row_groups)
+    n_merged = nrows + ngroups
+    p = sorted(rg.position for rg in row_groups)
+    group_positions_1 = [p[k] + k + 1 for k in range(ngroups)]
+    group_positions_set = set(group_positions_1)
+    sorted_rg = sorted(row_groups, key=lambda rg: rg.position)
+    pos_to_label = dict(zip(group_positions_1, (rg.label for rg in sorted_rg), strict=True))
+    merged = []
+    data_row_idx = 0
+    for r in range(1, n_merged + 1):
+        if r in group_positions_set:
+            merged.append([pos_to_label[r]] + [""] * (ncols - 1))
+        else:
+            merged.append(data_body[data_row_idx])
+            data_row_idx += 1
+    return merged, pos_to_label