feat: add odfpy-based workbook loader

Author: Arturo R Montesinos

pyproject.toml

@@ -17,7 +17,9 @@ name = "odsview-cli-python"
 version = "0.0.1"
 description = "Read-only terminal viewer for .ods (LibreOffice Calc) files"
 requires-python = ">=3.9"
-dependencies = []
+dependencies = [
+	"odfpy>=1.4.1",
+]
 
 [project.scripts]
 odsview = "odsview.cli:main"

src/odsview/container.py

@@ -0,0 +1,83 @@
+"""Container-level helpers for opening ODS workbooks.
+
+This module is responsible for working at the ZIP/container level and
+provides a narrow interface for the rest of the application. At this
+stage we only support **plain (unencrypted)** `.ods` files.
+
+Encryption support will be added in future milestones, as described in
+ADR-0002.
+"""
+
+from __future__ import annotations
+
+import zipfile
+from pathlib import Path
+from typing import BinaryIO
+
+
+class ODSContainerError(Exception):
+    """Base exception for container-related errors."""
+
+
+class ODSFileNotFoundError(ODSContainerError):
+    """Raised when the requested ODS file does not exist."""
+
+
+class ODSEncryptedError(ODSContainerError):
+    """Raised when the ODS file appears to be encrypted.
+
+    Encryption is not yet supported; this exception allows the caller to
+    surface a clear, testable error message.
+    """
+
+
+def open_ods_container(path: str | Path) -> zipfile.ZipFile:
+    """Open an ODS file as a ZIP container.
+
+    Parameters
+    ----------
+    path:
+        Path to the ODS file on disk.
+
+    Returns
+    -------
+    zipfile.ZipFile
+        An open ZipFile object. The caller is responsible for closing it.
+
+    Raises
+    ------
+    ODSFileNotFoundError
+        If the path does not exist or is not a file.
+    ODSContainerError
+        If the file is not a valid ZIP/ODS container.
+    ODSEncryptedError
+        Reserved for future use once encryption detection is implemented.
+    """
+
+    p = Path(path)
+    if not p.is_file():
+        raise ODSFileNotFoundError(f"ODS file not found: {p}")
+
+    try:
+        zf = zipfile.ZipFile(p)
+    except Exception as exc:  # pragma: no cover - zipfile error paths
+        raise ODSContainerError(f"Failed to open ODS container: {p}") from exc
+
+    # TODO: In a future milestone, inspect META-INF/manifest.xml here to
+    # decide whether the content is encrypted and raise ODSEncryptedError
+    # if necessary.
+
+    return zf
+
+
+def open_content_xml(zf: zipfile.ZipFile) -> BinaryIO:
+    """Return a file-like object for `content.xml` inside the ODS ZIP.
+
+    The caller is responsible for closing both the returned file object
+    (if applicable) and the underlying ZipFile.
+    """
+
+    try:
+        return zf.open("content.xml")
+    except KeyError as exc:  # pragma: no cover - malformed ODS
+        raise ODSContainerError("ODS container is missing content.xml") from exc

src/odsview/workbook.py

@@ -0,0 +1,73 @@
+"""Workbook abstraction built on top of odfpy.
+
+This module exposes a small, testable interface over an ODS workbook
+for the rest of the application. It delegates container work to
+:mod:`odsview.container`.
+
+At this milestone we support only plain (unencrypted) `.ods` files and a
+minimal feature set:
+
+- Open an ODS file.
+- List sheet names.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, List
+
+from odf.opendocument import load
+from odf.table import Table
+
+from .container import open_ods_container
+
+
+@dataclass
+class SheetInfo:
+    """Lightweight description of a sheet in a workbook."""
+
+    name: str
+
+
+@dataclass
+class Workbook:
+    """Simple wrapper around an ODS document.
+
+    For now this only exposes sheet metadata. More operations (row
+    iteration, cell access, etc.) can be added as milestones progress.
+    """
+
+    path: Path
+    _odf_doc: object
+
+    @property
+    def sheets(self) -> List[SheetInfo]:
+        """Return a list of sheets in the workbook.
+
+        The order matches the order in the underlying ODS document.
+        """
+
+        result: List[SheetInfo] = []
+        for table in self._odf_doc.getElementsByType(Table):  # type: ignore[no-any-return]
+            name = table.getAttribute("name") or ""
+            result.append(SheetInfo(name=name))
+        return result
+
+
+def load_workbook(path: str | Path) -> Workbook:
+    """Load a workbook from a `.ods` file.
+
+    This function uses :mod:`odsview.container` to open the file as a
+    ZIP container, then passes the path to :func:`odf.opendocument.load`.
+
+    Encryption detection/handling will be added to the container layer in
+    future milestones.
+    """
+
+    p = Path(path)
+    # Ensure the file exists and is a valid container first; this will
+    # raise well-typed container errors instead of generic exceptions.
+    with open_ods_container(p):
+        odf_doc = load(str(p))
+    return Workbook(path=p, _odf_doc=odf_doc)

tests/fixtures/simple.ods

@@ -1,4 +1,4 @@
-"""Smoke tests for the odsview CLI skeleton."""
+"""Smoke tests for the odsview CLI skeleton and basic loading."""
 
 from __future__ import annotations
 

tests/test_cli.py

@@ -0,0 +1,32 @@
+"""Tests for the odsview workbook and container layers.
+
+These tests currently exercise plain (unencrypted) `.ods` handling at a
+very shallow level, using a tiny fixture ODS file.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from odsview.workbook import Workbook, SheetInfo, load_workbook
+
+
+def test_load_workbook_and_list_sheets(tmp_path: Path) -> None:
+    """Smoke test that we can call load_workbook on a valid file.
+
+    This test expects a small fixture file committed under
+    `tests/fixtures/simple.ods`. It asserts that at least one sheet is
+    present and that sheet names are non-empty strings.
+    """
+
+    project_root = Path(__file__).resolve().parents[1]
+    fixture = project_root / "tests" / "fixtures" / "simple.ods"
+    assert fixture.is_file(), "Missing test fixture: tests/fixtures/simple.ods"
+
+    wb = load_workbook(fixture)
+    assert isinstance(wb, Workbook)
+
+    sheets = wb.sheets
+    assert sheets, "Expected at least one sheet in the workbook"
+    assert all(isinstance(s, SheetInfo) for s in sheets)
+    assert all(s.name for s in sheets)