feat: add mypy strict type checking and Prompt.__repr__

Author: practicalmind-dev

.github/workflows/ci.yml

@@ -23,4 +23,5 @@ jobs:
 
       - run: pip install -e ".[dev]"
       - run: ruff check .
+      - run: mypy graver/
       - run: pytest -q

graver/core.py

@@ -1,4 +1,5 @@
 from pathlib import Path
+from typing import Any
 
 from graver.exceptions import PromptNotFoundError
 from graver.storage import Storage
@@ -11,6 +12,9 @@ def __init__(self, name: str, base_dir: str = ".graver") -> None:
         self.name = name
         self._storage = Storage(base_dir=base_dir)
 
+    def __repr__(self) -> str:
+        return f"Prompt({self.name!r}, base_dir={str(self._storage._base)!r})"
+
     @staticmethod
     def list_all(base_dir: str = ".graver") -> list[str]:
         """Return the names of all saved prompts in the given base directory."""
@@ -34,7 +38,7 @@ def get(self, version: str | None = None) -> str:
         """Return the prompt text for the given version, or the latest if None."""
         return self._storage.get(self.name, version)
 
-    def log(self) -> list[dict]:
+    def log(self) -> list[dict[str, Any]]:
         """Return the full version history, oldest to newest, with is_main flag."""
         main = self._storage.get_main(self.name)
         history = self._storage.history(self.name)
@@ -63,7 +67,7 @@ def delete_version(self, version: str) -> None:
         """Delete a specific version; clears the main pointer if it was main."""
         self._storage.delete_version(self.name, version)
 
-    def diff(self, v1: str, v2: str) -> dict:
+    def diff(self, v1: str, v2: str) -> dict[str, list[str]]:
         """Return raw line-by-line diff between two versions."""
         return self._storage.diff(self.name, v1, v2)
 
@@ -73,10 +77,9 @@ def changes(self, v1: str | None = None, v2: str | None = None) -> str:
         if len(history) < 2:
             return "Need at least 2 versions to compare."
 
-        if v1 is None and v2 is None:
+        if v1 is None:
             v1 = history[-2]["version"]
-            v2 = history[-1]["version"]
-        elif v2 is None:
+        if v2 is None:
             v2 = history[-1]["version"]
 
         result = self._storage.diff(self.name, v1, v2)

graver/storage.py

@@ -2,6 +2,7 @@
 import json
 from datetime import datetime
 from pathlib import Path
+from typing import Any
 
 from graver.exceptions import (
     PromptNotFoundError,
@@ -57,7 +58,7 @@ def save(self, name: str, content: str) -> str:
 
         history_path = self._history_file(name)
         try:
-            history: list[dict] = (
+            history: list[dict[str, Any]] = (
                 json.loads(history_path.read_text(encoding="utf-8"))
                 if history_path.exists()
                 else []
@@ -94,7 +95,7 @@ def get(self, name: str, version: str | None = None) -> str:
 
         return target.read_text(encoding="utf-8")
 
-    def history(self, name: str) -> list[dict]:
+    def history(self, name: str) -> list[dict[str, Any]]:
         prompt_dir = self._prompt_dir(name)
         if not prompt_dir.exists():
             raise PromptNotFoundError(
@@ -105,9 +106,12 @@ def history(self, name: str) -> list[dict]:
         if not history_path.exists():
             return []
 
-        return json.loads(history_path.read_text(encoding="utf-8"))
+        result: list[dict[str, Any]] = json.loads(
+            history_path.read_text(encoding="utf-8")
+        )
+        return result
 
-    def diff(self, name: str, v1: str, v2: str) -> dict:
+    def diff(self, name: str, v1: str, v2: str) -> dict[str, list[str]]:
         lines1 = self.get(name, v1).splitlines(keepends=True)
         lines2 = self.get(name, v2).splitlines(keepends=True)
 
@@ -151,7 +155,9 @@ def delete_version(self, name: str, version: str) -> None:
         history_path = self._history_file(name)
         if history_path.exists():
             try:
-                history = json.loads(history_path.read_text(encoding="utf-8"))
+                history: list[dict[str, Any]] = json.loads(
+                    history_path.read_text(encoding="utf-8")
+                )
                 history = [e for e in history if e["version"] != version]
                 history_path.write_text(
                     json.dumps(history, indent=2, ensure_ascii=False), encoding="utf-8"
@@ -182,5 +188,6 @@ def get_main(self, name: str) -> str | None:
         main_path = self._main_file(name)
         if not main_path.exists():
             return None
-        data = json.loads(main_path.read_text(encoding="utf-8"))
-        return data.get("version")
+        data: dict[str, Any] = json.loads(main_path.read_text(encoding="utf-8"))
+        version: str | None = data.get("version")
+        return version

pyproject.toml

@@ -35,6 +35,7 @@ dev = [
   "pytest>=7.0",
   "black>=23.0",
   "ruff>=0.1.0",
+  "mypy>=1.10",
 ]
 
 [project.urls]
@@ -60,3 +61,8 @@ exclude = ["tests/"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["graver"]