feat: add odsview CLI skeleton and tests

Author: Arturo R Montesinos

pyproject.toml

@@ -11,3 +11,13 @@ exclude = ["^docs/curation/"]
 [build-system]
 requires = ["setuptools>=68", "wheel"]
 build-backend = "setuptools.build_meta"
+
+[project]
+name = "odsview-cli-python"
+version = "0.0.1"
+description = "Read-only terminal viewer for .ods (LibreOffice Calc) files"
+requires-python = ">=3.9"
+dependencies = []
+
+[project.scripts]
+odsview = "odsview.cli:main"

src/odsview/__init__.py

@@ -0,0 +1,6 @@
+"""odsview package init.
+
+For now, this only exposes the package version when defined.
+"""
+
+__all__ = []

src/odsview/cli.py

@@ -0,0 +1,54 @@
+"""CLI entry point for odsview.
+
+This is a minimal placeholder implementing only ``--help`` for now.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Sequence
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="odsview",
+        description=(
+            "Read-only terminal viewer for .ods (LibreOffice Calc) files. "
+            "Currently, only basic skeleton functionality is implemented."
+        ),
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        help="Path to the .ods file to view (not yet implemented)",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point for the odsview CLI.
+
+    For now, this function only parses arguments and prints help when
+    called without a file. Real functionality (loading and rendering
+    .ods workbooks) will be added in future milestones.
+    """
+
+    if argv is None:
+        argv = sys.argv[1:]
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.file is None:
+        # For now, just print help and exit with code 0.
+        parser.print_help(sys.stdout)
+        return 0
+
+    # Placeholder for future implementation.
+    parser.error("viewing .ods files is not implemented yet")
+    return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

tests/test_cli.py

@@ -0,0 +1,35 @@
+"""Smoke tests for the odsview CLI skeleton."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def run_cli(*args: str) -> subprocess.CompletedProcess[str]:
+    project_root = Path(__file__).resolve().parents[1]
+    env = dict(**os.environ)
+    # Ensure the package can be imported via the project root on sys.path.
+    env.setdefault("PYTHONPATH", str(project_root / "src"))
+    return subprocess.run(
+        [sys.executable, "-m", "odsview.cli", *args],
+        cwd=project_root,
+        text=True,
+        capture_output=True,
+        env=env,
+        check=False,
+    )
+
+
+def test_help_exits_zero() -> None:
+    result = run_cli("--help")
+    assert result.returncode == 0
+    assert "usage:" in result.stdout.lower()
+
+
+def test_no_args_prints_help_and_exits_zero() -> None:
+    result = run_cli()
+    assert result.returncode == 0
+    assert "usage:" in result.stdout.lower()