Implement range-based table view and fixtures

Author: Arturo R Montesinos

README.md

@@ -25,10 +25,8 @@ This project is in an **early experimental** phase.
   `.ods` files and enumerate sheet names.
 - The CLI currently supports:
   - `--list-sheets FILE.ods` → list sheet names (ADR-0003).
+  - A simple range-based table view for cell contents (ADR-0004).
   - Help/usage output when invoked without arguments.
-- A range-based table view mode (ADR-0004) is specified but **not yet
-  implemented**; the README and `AI_CURATOR_RECIPE.md` describe this as
-  upcoming work.
 
 ## Quickstart (local development)
 
@@ -47,7 +45,9 @@ To see the current CLI behavior:
 ```bash
 odsview --help
 odsview --list-sheets tests/fixtures/simple.ods
-odsview path/to/file.ods  # viewing cell contents is not yet implemented
+odsview tests/fixtures/table_small.ods
+odsview --sheet Sheet2 tests/fixtures/table_small.ods
+odsview --range A1:C3 tests/fixtures/table_small.ods
 ```
 
 ## Curation & Guardrails

src/odsview/cli.py

@@ -7,10 +7,12 @@
 
 import argparse
 import sys
+from dataclasses import dataclass
 from pathlib import Path
-from typing import Sequence
+from typing import Sequence, Tuple
 
-from .workbook import load_workbook
+from .workbook import Workbook, load_workbook
+from .tableview import ParsedRange as TVParsedRange, iter_range as tv_iter_range
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -31,9 +33,116 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="List sheet names for the given .ods file and exit",
     )
+    parser.add_argument(
+        "--sheet",
+        metavar="NAME",
+        help="Sheet name to view (defaults to first sheet)",
+    )
+    parser.add_argument(
+        "--range",
+        metavar="RANGE",
+        help="Cell range to view (e.g. A1:E10). Defaults to A1:H10 if omitted",
+    )
     return parser
 
 
+def _col_label_to_index(label: str) -> int:
+    """Convert a column label like 'A' or 'C' to a 1-based index.
+
+    This initial implementation supports A-Z only as required for the
+    small fixtures; it is structured so that multi-letter columns can be
+    added later without changing the public CLI contract.
+    """
+
+    if not label.isalpha() or len(label) != 1:
+        raise ValueError(f"unsupported column label: {label!r}")
+    return ord(label.upper()) - ord("A") + 1
+
+
+def _parse_cell_ref(ref: str) -> Tuple[int, int]:
+    """Parse a minimal cell reference like 'A1' into (row, col)."""
+
+    if not ref:
+        raise ValueError("empty cell reference")
+
+    col_part = ""
+    row_part = ""
+    for ch in ref:
+        if ch.isalpha():
+            if row_part:
+                raise ValueError(f"invalid cell reference: {ref!r}")
+            col_part += ch
+        elif ch.isdigit():
+            row_part += ch
+        else:
+            raise ValueError(f"invalid character in cell reference: {ref!r}")
+
+    if not col_part or not row_part:
+        raise ValueError(f"invalid cell reference: {ref!r}")
+
+    col = _col_label_to_index(col_part)
+    row = int(row_part)
+    if row < 1:
+        raise ValueError(f"row index must be >= 1 in {ref!r}")
+    return row, col
+
+
+def _parse_range_spec(spec: str | None) -> TVParsedRange:
+    """Parse a RANGE argument like 'A1:E10' into coordinates.
+
+    If ``spec`` is ``None``, the default window A1:H10 is used.
+    A single-cell reference like 'A1' is interpreted as the top-left
+    corner of the default window.
+    """
+
+    default = TVParsedRange(start_row=1, end_row=10, start_col=1, end_col=8)
+    if spec is None:
+        return default
+
+    parts = spec.split(":")
+    if len(parts) == 1:
+        start = parts[0]
+        start_row, start_col = _parse_cell_ref(start)
+        return TVParsedRange(
+            start_row=start_row,
+            end_row=start_row + (default.end_row - default.start_row),
+            start_col=start_col,
+            end_col=start_col + (default.end_col - default.start_col),
+        )
+    if len(parts) == 2:
+        start, end = parts
+        start_row, start_col = _parse_cell_ref(start)
+        end_row, end_col = _parse_cell_ref(end)
+        return TVParsedRange(
+            start_row=min(start_row, end_row),
+            end_row=max(start_row, end_row),
+            start_col=min(start_col, end_col),
+            end_col=max(start_col, end_col),
+        )
+
+    raise ValueError(f"invalid range specification: {spec!r}")
+
+
+def _render_table(workbook: Workbook, sheet_name: str | None, rng: TVParsedRange) -> None:
+    """Render a rectangular table to stdout using a simple text layout."""
+
+    rows = list(tv_iter_range(workbook._odf_doc, sheet_name, rng))
+
+    if not rows:
+        return
+
+    # Compute column widths.
+    num_cols = len(rows[0])
+    widths = [0] * num_cols
+    for row in rows:
+        for idx, cell in enumerate(row):
+            widths[idx] = max(widths[idx], len(cell))
+
+    for row in rows:
+        padded = [cell.ljust(widths[idx]) for idx, cell in enumerate(row)]
+        print("  ".join(padded))
+
+
 def main(argv: Sequence[str] | None = None) -> int:
     """Entry point for the odsview CLI.
 
@@ -53,7 +162,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         parser.print_help(sys.stdout)
         return 0
 
-    # --list-sheets requires a file.
+    # --list-sheets requires a file and ignores table-view options.
     if args.list_sheets:
         if args.file is None:
             parser.error("--list-sheets requires a FILE argument")
@@ -73,11 +182,38 @@ def main(argv: Sequence[str] | None = None) -> int:
 
         return 0
 
-    # Any other use of FILE remains unimplemented for now.
-    if args.file is not None:
-        parser.error("viewing .ods files is not implemented yet")
+    # Table view mode: requires a file.
+    if args.file is None and (args.sheet or args.range):
+        parser.error("table view requires a FILE argument")
         return 2
 
+    if args.file is not None:
+        try:
+            workbook = load_workbook(Path(args.file))
+        except FileNotFoundError as exc:  # pragma: no cover - exercised via integration tests
+            print(str(exc), file=sys.stderr)
+            return 1
+        except Exception as exc:  # pragma: no cover - generic fallback
+            print(str(exc), file=sys.stderr)
+            return 1
+
+        try:
+            rng = _parse_range_spec(args.range)
+        except ValueError as exc:
+            print(str(exc), file=sys.stderr)
+            return 2
+
+        try:
+            _render_table(workbook, args.sheet, rng)
+        except KeyError as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+        except ValueError as exc:
+            print(str(exc), file=sys.stderr)
+            return 2
+
+        return 0
+
     # Fallback: show help.
     parser.print_help(sys.stdout)
     return 0

src/odsview/tableview.py

@@ -0,0 +1,99 @@
+"""Helpers for rendering a rectangular table view from an ODS file.
+
+This module deliberately works directly with odfpy's DOM rather than
+extending :mod:`odsview.workbook`. The workbook abstraction currently
+exposes only sheet metadata; higher‑level viewing behaviour is kept
+separate for now to avoid destabilising existing callers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, List, Sequence
+
+from odf.table import Table, TableCell, TableRow
+from odf.text import P
+
+
+@dataclass
+class ParsedRange:
+    start_row: int
+    end_row: int
+    start_col: int
+    end_col: int
+
+
+def _iter_sheets(odf_doc: object) -> Iterable[Table]:
+    """Yield table elements in document order."""
+
+    # getElementsByType is provided by odfpy's document classes.
+    return odf_doc.getElementsByType(Table)  # type: ignore[no-any-return]
+
+
+def _find_sheet(odf_doc: object, name: str | None) -> Table:
+    """Return the requested sheet or the first sheet if *name* is None.
+
+    Raises ``KeyError`` if a specific *name* is requested but not found,
+    or ``ValueError`` if the document has no sheets at all.
+    """
+
+    sheets = list(_iter_sheets(odf_doc))
+    if not sheets:
+        raise ValueError("workbook contains no sheets")
+
+    if name is None:
+        return sheets[0]
+
+    for table in sheets:
+        if table.getAttribute("name") == name:
+            return table
+
+    raise KeyError(f"sheet not found: {name}")
+
+
+def _cell_text(cell: TableCell) -> str:
+    """Extract visible text from a table cell.
+
+    odfpy represents cell text as ``text:p`` children rather than via a
+    plain attribute in many cases. For our fixtures, concatenating all
+    paragraph texts with a single space is sufficient.
+    """
+
+    pieces: List[str] = []
+    for p in cell.getElementsByType(P):
+        # Each P instance behaves like an element whose string
+        # representation yields its textual content.
+        text = str(p)
+        if text:
+            pieces.append(text)
+    return " ".join(pieces)
+
+
+def iter_range(
+    odf_doc: object,
+    sheet_name: str | None,
+    rng: ParsedRange,
+) -> Iterable[Sequence[str]]:
+    """Iterate over rows of text cells for the given rectangular range.
+
+    Row and column indices in *rng* are 1‑based and inclusive. Cells
+    missing from the underlying sheet are yielded as empty strings.
+    """
+
+    table = _find_sheet(odf_doc, sheet_name)
+
+    # Collect rows within the desired index window.
+    rows: List[Sequence[str]] = []
+    for row_idx, row in enumerate(table.getElementsByType(TableRow), start=1):
+        if row_idx < rng.start_row or row_idx > rng.end_row:
+            continue
+
+        cells = list(row.getElementsByType(TableCell))
+        row_values: List[str] = []
+        for col_idx in range(rng.start_col, rng.end_col + 1):
+            cell: TableCell | None = cells[col_idx - 1] if col_idx - 1 < len(cells) else None
+            row_values.append(_cell_text(cell) if cell is not None else "")
+
+        rows.append(row_values)
+
+    return rows