sheetdelta 0.1.0__py3-none-any.whl

sheetdelta/__init__.py

@@ -0,0 +1,65 @@
+"""sheetdelta: diff Excel workbooks without Excel.
+
+Compares two .xlsx files cell by cell, including the formulas, the values
+Excel cached, and the dependency graph that says which cells a change
+reaches. Nothing is evaluated -- the reader only looks at what Excel already
+stored.
+
+Typical use is a CI check: fail the build when a formula edit corrupts a
+downstream total, pass it when the change is cosmetic.
+
+    from sheetdelta import read_workbook, diff_workbooks
+
+    result = diff_workbooks(read_workbook("old.xlsx"), read_workbook("new.xlsx"))
+    for change in result.breaking:
+        print(change.ref, change.detail, change.affected)
+"""
+
+from __future__ import annotations
+
+from .differ import CellChange, ChangeKind, DiffResult, Severity, SheetChange, diff_workbooks
+from .errors import SheetDeltaError, UnsupportedFormatError, WorkbookReadError
+from .model import (
+    Cell,
+    CellKind,
+    CellRef,
+    RangeRef,
+    Reference,
+    Sheet,
+    Workbook,
+    column_letter,
+    column_number,
+)
+from .reader import read_workbook
+from .references import extract_references
+from .report import exit_code, render_json, render_text, to_dict
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Cell",
+    "CellChange",
+    "CellKind",
+    "CellRef",
+    "ChangeKind",
+    "DiffResult",
+    "RangeRef",
+    "Reference",
+    "Severity",
+    "Sheet",
+    "SheetChange",
+    "SheetDeltaError",
+    "UnsupportedFormatError",
+    "Workbook",
+    "WorkbookReadError",
+    "__version__",
+    "column_letter",
+    "column_number",
+    "diff_workbooks",
+    "exit_code",
+    "extract_references",
+    "read_workbook",
+    "render_json",
+    "render_text",
+    "to_dict",
+]

sheetdelta/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for ``python -m sheetdelta``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sheetdelta/audit.py

@@ -0,0 +1,169 @@
+"""Inspect a single workbook for defects a diff cannot see.
+
+An audit answers "is this file sound", not "what changed". Two defects are
+worth reporting, and both are unambiguous rather than heuristic:
+
+* a formula pointing at a sheet that does not exist, which Excel shows as
+  ``#REF!``; and
+* a circular reference, a cell that depends on itself through some chain of
+  other cells, which Excel refuses to calculate at all.
+
+Deliberately not checked: a reference to a cell that is merely empty. That is
+normal in a spreadsheet, and flagging it would make the audit cry wolf on
+every real file.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .model import Cell, CellKind, CellRef, Workbook
+
+
+@dataclass
+class BrokenReference:
+    """A formula reference to a sheet that is not in the workbook."""
+
+    ref: CellRef
+    formula: str
+    target: str
+    reason: str
+
+
+@dataclass
+class CircularReference:
+    """A cycle of cells that each depend on the next, ending where it started."""
+
+    cells: list[CellRef]
+
+    @property
+    def display(self) -> str:
+        return " -> ".join(str(ref) for ref in self.cells)
+
+
+@dataclass
+class AuditResult:
+    path: str
+    sheets: list[str] = field(default_factory=list)
+    formula_count: int = 0
+    cell_count: int = 0
+    defined_names: dict[str, str] = field(default_factory=dict)
+    broken: list[BrokenReference] = field(default_factory=list)
+    cycles: list[CircularReference] = field(default_factory=list)
+
+    @property
+    def is_sound(self) -> bool:
+        return not self.broken and not self.cycles
+
+    @property
+    def issue_count(self) -> int:
+        return len(self.broken) + len(self.cycles)
+
+
+def audit_workbook(workbook: Workbook) -> AuditResult:
+    """Check a workbook for broken references and circular references."""
+    result = AuditResult(
+        path=workbook.path,
+        sheets=workbook.sheet_names,
+        defined_names=dict(workbook.defined_names),
+    )
+
+    for sheet in workbook.sheets:
+        for cell in sheet.cells.values():
+            result.cell_count += 1
+            if cell.kind is CellKind.FORMULA:
+                result.formula_count += 1
+                result.broken.extend(_missing_sheets(cell, workbook))
+
+    result.broken.sort(key=lambda b: (b.ref.sheet, b.ref.row, b.ref.col))
+    result.cycles = _find_cycles(workbook)
+    return result
+
+
+def _missing_sheets(cell: Cell, workbook: Workbook) -> list[BrokenReference]:
+    """Every reference in one formula that names a sheet that is not there."""
+    out: list[BrokenReference] = []
+    for reference in sorted(cell.refs, key=str):
+        if workbook.sheet_by_name(reference.sheet) is None:
+            out.append(
+                BrokenReference(
+                    ref=cell.ref,
+                    formula=cell.formula or "",
+                    target=str(reference),
+                    reason=f"sheet '{reference.sheet}' does not exist",
+                )
+            )
+    return out
+
+
+def _find_cycles(workbook: Workbook) -> list[CircularReference]:
+    """Find circular references across the whole workbook.
+
+    Walks the dependency graph depth-first, tracking the cells on the current
+    path. Reaching a cell already on the path closes a cycle, and the slice of
+    the path from that cell onwards is the loop to report.
+    """
+    graph = _dependency_graph(workbook)
+    found: list[CircularReference] = []
+    seen: set[CellRef] = set()
+    reported: set[frozenset[CellRef]] = set()
+
+    for start in sorted(graph, key=lambda r: (r.sheet, r.row, r.col)):
+        if start in seen:
+            continue
+        _walk(start, graph, [], set(), seen, found, reported)
+
+    return found
+
+
+def _walk(
+    node: CellRef,
+    graph: dict[CellRef, set[CellRef]],
+    path: list[CellRef],
+    on_path: set[CellRef],
+    seen: set[CellRef],
+    found: list[CircularReference],
+    reported: set[frozenset[CellRef]],
+) -> None:
+    path.append(node)
+    on_path.add(node)
+
+    for neighbour in sorted(graph.get(node, ()), key=lambda r: (r.sheet, r.row, r.col)):
+        if neighbour in on_path:
+            cycle = path[path.index(neighbour) :]
+            key = frozenset(cycle)
+            if key not in reported:
+                reported.add(key)
+                found.append(CircularReference(cells=[*cycle, neighbour]))
+        elif neighbour not in seen:
+            _walk(neighbour, graph, path, on_path, seen, found, reported)
+
+    path.pop()
+    on_path.discard(node)
+    seen.add(node)
+
+
+def _dependency_graph(workbook: Workbook) -> dict[CellRef, set[CellRef]]:
+    """Map each cell to the cells it reads, ignoring self-reads and blanks.
+
+    Cross-sheet references are followed to the sheet they name, so a cycle that
+    runs from one sheet into another is still found.
+    """
+    graph: dict[CellRef, set[CellRef]] = {}
+    for sheet in workbook.sheets:
+        for cell in sheet.cells.values():
+            if cell.kind is not CellKind.FORMULA:
+                continue
+            targets: set[CellRef] = set()
+            for reference in cell.refs:
+                target_sheet = workbook.sheet_by_name(reference.sheet)
+                if target_sheet is None:
+                    continue
+                targets.update(
+                    ref
+                    for ref in target_sheet.cells
+                    if ref != cell.ref and reference.contains(ref)
+                )
+            if targets:
+                graph[cell.ref] = targets
+    return graph

sheetdelta/cli.py

@@ -0,0 +1,140 @@
+"""The ``sheetdelta`` command line.
+
+Two subcommands: ``diff`` compares two workbooks, ``audit`` inspects one. The
+exit code is the point of the tool in CI, so ``--fail-on`` is explicit rather
+than implied.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+
+from . import __version__
+from .audit import AuditResult, audit_workbook
+from .differ import diff_workbooks
+from .errors import SheetDeltaError
+from .reader import read_workbook
+from .report import exit_code, render_json, render_text
+
+FAIL_ON = ("never", "any", "breaking")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sheetdelta",
+        description="Diff Excel workbooks without Excel.",
+        epilog="Exit status: 0 no changes worth failing on, 1 changes found, 2 error.",
+    )
+    parser.add_argument("--version", action="version", version=f"sheetdelta {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    diff = sub.add_parser("diff", help="compare two workbooks")
+    diff.add_argument("old", metavar="OLD.xlsx", help="the earlier workbook")
+    diff.add_argument("new", metavar="NEW.xlsx", help="the later workbook")
+    diff.add_argument("--json", action="store_true", help="emit JSON instead of text")
+    diff.add_argument(
+        "--fail-on",
+        choices=FAIL_ON,
+        default="breaking",
+        help="when to exit non-zero (default: breaking)",
+    )
+
+    audit = sub.add_parser("audit", help="inspect one workbook for broken references")
+    audit.add_argument("workbook", metavar="FILE.xlsx", help="the workbook to inspect")
+    audit.add_argument("--json", action="store_true", help="emit JSON")
+    audit.add_argument(
+        "--fail-on",
+        choices=FAIL_ON,
+        default="any",
+        help="when to exit non-zero (default: any)",
+    )
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "diff":
+            return _cmd_diff(args)
+        if args.command == "audit":
+            return _cmd_audit(args)
+    except SheetDeltaError as exc:
+        print(f"sheetdelta: {exc}", file=sys.stderr)
+        return 2
+    return 2
+
+
+def _cmd_diff(args: argparse.Namespace) -> int:
+    result = diff_workbooks(read_workbook(args.old), read_workbook(args.new))
+    print(render_json(result) if args.json else render_text(result))
+    return exit_code(result, args.fail_on)
+
+
+def _cmd_audit(args: argparse.Namespace) -> int:
+    result = audit_workbook(read_workbook(args.workbook))
+    print(render_audit_json(result) if args.json else render_audit_text(result))
+    if args.fail_on == "never":
+        return 0
+    if args.fail_on == "any":
+        return 1 if result.issue_count else 0
+    return 0
+
+
+def render_audit_text(result: AuditResult) -> str:
+    """Render an audit for a human."""
+    lines = [f"{result.path}"]
+    lines.append(
+        f"  {len(result.sheets)} sheet(s), {result.cell_count} cell(s), "
+        f"{result.formula_count} formula(s)"
+    )
+    if result.defined_names:
+        lines.append(f"  {len(result.defined_names)} defined name(s)")
+
+    if result.is_sound:
+        lines.append("")
+        lines.append("No broken references, no circular references.")
+        return "\n".join(lines)
+
+    if result.broken:
+        lines.append("")
+        lines.append(f"{len(result.broken)} broken reference(s):")
+        for broken in result.broken:
+            lines.append(f"  !! {broken.ref.a1:<6} {broken.target}")
+            lines.append(f"        {broken.reason}")
+            lines.append(f"        ={broken.formula}")
+
+    if result.cycles:
+        lines.append("")
+        lines.append(f"{len(result.cycles)} circular reference(s):")
+        for cycle in result.cycles:
+            lines.append(f"  !! {cycle.display}")
+
+    return "\n".join(lines)
+
+
+def render_audit_json(result: AuditResult) -> str:
+    return json.dumps(
+        {
+            "path": result.path,
+            "sheets": result.sheets,
+            "cells": result.cell_count,
+            "formulas": result.formula_count,
+            "sound": result.is_sound,
+            "broken": [
+                {
+                    "cell": str(b.ref),
+                    "target": b.target,
+                    "reason": b.reason,
+                    "formula": f"={b.formula}",
+                }
+                for b in result.broken
+            ],
+            "cycles": [[str(ref) for ref in cycle.cells] for cycle in result.cycles],
+        },
+        indent=2,
+    )
+