chore: clean up docstrings and remove module-level comments

Author: baranylcn

graver/__init__.py

@@ -1,8 +1,5 @@
 """graver — Git-like version control for LLM prompts.
 
-Save, diff, and roll back prompt versions with a simple Python API.
-All data is stored as plain text files under a ``.graver/`` directory.
-
 Example::
 
     from graver import Prompt

graver/cli.py

@@ -1,5 +1,3 @@
-"""Command-line interface for graver."""
-
 import argparse
 import sys
 

graver/core.py

@@ -1,58 +1,27 @@
-"""Public-facing API for graver."""
-
 from pathlib import Path
 
 from graver.exceptions import PromptNotFoundError
 from graver.storage import Storage
 
 
 class Prompt:
-    """Git-like version control for a single named prompt.
-
-    Args:
-        name: Unique identifier for this prompt.
-        base_dir: Root directory for all prompt storage. Defaults to ".graver".
-    """
+    """Git-like version control for a single named prompt."""
 
     def __init__(self, name: str, base_dir: str = ".graver") -> None:
         self.name = name
         self._storage = Storage(base_dir=base_dir)
 
     @staticmethod
     def list_all(base_dir: str = ".graver") -> list[str]:
-        """Return the names of all saved prompts in the given base directory.
-
-        Args:
-            base_dir: Root directory for all prompt storage.
-
-        Returns:
-            A sorted list of prompt name strings.
-        """
+        """Return the names of all saved prompts in the given base directory."""
         return Storage(base_dir=base_dir).list_prompts()
 
     def save(self, content: str) -> str:
-        """Save a new version of this prompt.
-
-        Args:
-            content: The prompt text to persist.
-
-        Returns:
-            The version string for the saved version (e.g. "v1").
-        """
+        """Save a new version and return its version string (e.g. "v1")."""
         return self._storage.save(self.name, content)
 
     def save_from_file(self, filepath: str) -> str:
-        """Read prompt content from a file and save it as a new version.
-
-        Args:
-            filepath: Path to the file whose contents will be saved.
-
-        Returns:
-            The version string for the saved version (e.g. "v1").
-
-        Raises:
-            PromptNotFoundError: If the specified file does not exist.
-        """
+        """Read content from a file and save it as a new version."""
         path = Path(filepath)
         if not path.exists():
             raise PromptNotFoundError(
@@ -62,50 +31,23 @@ def save_from_file(self, filepath: str) -> str:
         return self.save(content)
 
     def get(self, version: str | None = None) -> str:
-        """Retrieve a version of this prompt.
-
-        Args:
-            version: Version string to retrieve (e.g. "v2"). If None,
-                returns the latest saved version.
-
-        Returns:
-            The prompt text for the requested version.
-        """
+        """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]:
-        """Return the full version history of this prompt.
-
-        Returns:
-            A list of dicts ordered from oldest to newest. Each dict
-            contains "version" (str), "timestamp" (str), and "is_main" (bool).
-        """
+        """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)
         for entry in history:
             entry["is_main"] = entry["version"] == main
         return history
 
     def set_main(self, version: str) -> None:
-        """Mark a specific version as the main (canonical) version.
-
-        Args:
-            version: Version string to mark as main (e.g. "v2").
-
-        Raises:
-            VersionNotFoundError: If the version does not exist.
-        """
+        """Pin a version as the canonical main."""
         self._storage.set_main(self.name, version)
 
     def get_main(self) -> str:
-        """Return the content of the main version.
-
-        Returns:
-            The prompt text of the main version.
-
-        Raises:
-            PromptNotFoundError: If no main version has been set.
-        """
+        """Return the content of the pinned main version."""
         version = self._storage.get_main(self.name)
         if version is None:
             raise PromptNotFoundError(
@@ -114,56 +56,19 @@ def get_main(self) -> str:
         return self._storage.get(self.name, version)
 
     def delete_prompt(self) -> None:
-        """Delete this prompt and all its versions.
-
-        Removes all version files, history, and the main pointer.
-
-        Raises:
-            PromptNotFoundError: If the prompt does not exist.
-            StorageError: If the directory removal fails.
-        """
+        """Delete this prompt and all its versions."""
         self._storage.delete_prompt(self.name)
 
     def delete_version(self, version: str) -> None:
-        """Delete a specific version of this prompt.
-
-        Removes the version file and its history entry. If the deleted version
-        was marked as main, the main pointer is also cleared.
-
-        Args:
-            version: Version string to delete (e.g. "v2").
-
-        Raises:
-            VersionNotFoundError: If the version does not exist.
-            StorageError: If the file delete operation fails.
-        """
+        """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:
-        """Compute a line-by-line diff between two versions.
-
-        Args:
-            v1: The base version string (e.g. "v1").
-            v2: The target version string (e.g. "v2").
-
-        Returns:
-            A dict with keys "added", "removed", and "unchanged", each
-            containing a list of strings representing the changed lines.
-        """
+        """Return raw line-by-line diff between two versions."""
         return self._storage.diff(self.name, v1, v2)
 
     def changes(self, v1: str | None = None, v2: str | None = None) -> str:
-        """Return a formatted change report between two versions.
-
-        If no versions are specified, compares the last two saved versions.
-
-        Args:
-            v1: Base version (e.g. "v1"). If None, uses second-to-last.
-            v2: Target version (e.g. "v2"). If None, uses latest.
-
-        Returns:
-            A formatted string showing added and removed lines.
-        """
+        """Return a formatted change report; defaults to the last two versions."""
         history = self._storage.history(self.name)
         if len(history) < 2:
             return "Need at least 2 versions to compare."
@@ -190,14 +95,7 @@ def changes(self, v1: str | None = None, v2: str | None = None) -> str:
         return "\n".join(lines)
 
     def show(self, version: str | None = None) -> str:
-        """Return a version's full content with a formatted header.
-
-        Args:
-            version: Version to display (e.g. "v2"). If None, shows latest.
-
-        Returns:
-            A formatted string with header and prompt content.
-        """
+        """Return a version's content with a formatted header."""
         history = self._storage.history(self.name)
         content = self._storage.get(self.name, version)
 

graver/exceptions.py

@@ -1,6 +1,3 @@
-"""Custom exceptions for the graver library."""
-
-
 class GraverError(Exception):
     """Base class for all graver errors."""
 

graver/storage.py

@@ -1,5 +1,3 @@
-"""File-system storage backend for graver."""
-
 import difflib
 import json
 from datetime import datetime
@@ -13,11 +11,7 @@
 
 
 class Storage:
-    """Handles all file system operations for graver.
-
-    Args:
-        base_dir: Root directory for all prompt storage.
-    """
+    """File-system backend; stores each prompt version as a plain-text file."""
 
     def __init__(self, base_dir: str = ".graver") -> None:
         self._base = Path(base_dir).resolve()
@@ -50,18 +44,6 @@ def _latest_version_num(self, prompt_dir: Path) -> int:
         return max(int(f.stem[1:]) for f in files)
 
     def save(self, name: str, content: str) -> str:
-        """Save a new version of a prompt.
-
-        Args:
-            name: Prompt identifier.
-            content: The prompt text to persist.
-
-        Returns:
-            The version string for the saved version (e.g. "v1").
-
-        Raises:
-            StorageError: If any file write operation fails.
-        """
         prompt_dir = self._prompt_dir(name)
         prompt_dir.mkdir(parents=True, exist_ok=True)
 
@@ -95,19 +77,6 @@ def save(self, name: str, content: str) -> str:
         return version
 
     def get(self, name: str, version: str | None = None) -> str:
-        """Retrieve the content of a prompt version.
-
-        Args:
-            name: Prompt identifier.
-            version: Version string to retrieve. If None, returns the latest.
-
-        Returns:
-            The prompt text for the requested version.
-
-        Raises:
-            PromptNotFoundError: If the prompt directory does not exist.
-            VersionNotFoundError: If the requested version file does not exist.
-        """
         prompt_dir = self._prompt_dir(name)
         if not prompt_dir.exists():
             raise PromptNotFoundError(
@@ -126,17 +95,6 @@ def get(self, name: str, version: str | None = None) -> str:
         return target.read_text(encoding="utf-8")
 
     def history(self, name: str) -> list[dict]:
-        """Return the version history for a prompt.
-
-        Args:
-            name: Prompt identifier.
-
-        Returns:
-            A list of dicts with keys "version" and "timestamp".
-
-        Raises:
-            PromptNotFoundError: If the prompt directory does not exist.
-        """
         prompt_dir = self._prompt_dir(name)
         if not prompt_dir.exists():
             raise PromptNotFoundError(
@@ -150,19 +108,6 @@ def history(self, name: str) -> list[dict]:
         return json.loads(history_path.read_text(encoding="utf-8"))
 
     def diff(self, name: str, v1: str, v2: str) -> dict:
-        """Compute a line-by-line diff between two versions.
-
-        Args:
-            name: Prompt identifier.
-            v1: The base version string (e.g. "v1").
-            v2: The target version string (e.g. "v2").
-
-        Returns:
-            A dict with keys "added", "removed", and "unchanged".
-
-        Raises:
-            VersionNotFoundError: If either version does not exist.
-        """
         lines1 = self.get(name, v1).splitlines(keepends=True)
         lines2 = self.get(name, v2).splitlines(keepends=True)
 
@@ -179,16 +124,6 @@ def diff(self, name: str, v1: str, v2: str) -> dict:
         return {"added": added, "removed": removed, "unchanged": unchanged}
 
     def set_main(self, name: str, version: str) -> None:
-        """Mark a specific version as the main (canonical) version.
-
-        Args:
-            name: Prompt identifier.
-            version: Version string to mark as main (e.g. "v2").
-
-        Raises:
-            VersionNotFoundError: If the version does not exist.
-            StorageError: If the file write fails.
-        """
         if not self._version_file(name, version).exists():
             raise VersionNotFoundError(
                 f"Version '{version}' not found for prompt '{name}'."
@@ -202,19 +137,6 @@ def set_main(self, name: str, version: str) -> None:
             raise StorageError(f"Failed to write main for '{name}': {exc}") from exc
 
     def delete_version(self, name: str, version: str) -> None:
-        """Delete a specific version of a prompt.
-
-        Removes the version file and its entry from history. If the deleted
-        version was marked as main, the main pointer is also cleared.
-
-        Args:
-            name: Prompt identifier.
-            version: Version string to delete (e.g. "v2").
-
-        Raises:
-            VersionNotFoundError: If the version does not exist.
-            StorageError: If the file delete operation fails.
-        """
         version_path = self._version_file(name, version)
         if not version_path.exists():
             raise VersionNotFoundError(
@@ -243,18 +165,6 @@ def delete_version(self, name: str, version: str) -> None:
             self._main_file(name).unlink(missing_ok=True)
 
     def delete_prompt(self, name: str) -> None:
-        """Delete a prompt and all its versions.
-
-        Removes the entire prompt directory including all version files,
-        history, and the main pointer.
-
-        Args:
-            name: Prompt identifier.
-
-        Raises:
-            PromptNotFoundError: If the prompt does not exist.
-            StorageError: If the directory removal fails.
-        """
         prompt_dir = self._prompt_dir(name)
         if not prompt_dir.exists():
             raise PromptNotFoundError(f"Prompt '{name}' not found.")
@@ -266,22 +176,9 @@ def delete_prompt(self, name: str) -> None:
             raise StorageError(f"Failed to delete prompt '{name}': {exc}") from exc
 
     def list_prompts(self) -> list[str]:
-        """Return the names of all saved prompts.
-
-        Returns:
-            A sorted list of prompt name strings.
-        """
         return sorted(d.name for d in self._base.iterdir() if d.is_dir())
 
     def get_main(self, name: str) -> str | None:
-        """Return the version string marked as main, or None if not set.
-
-        Args:
-            name: Prompt identifier.
-
-        Returns:
-            The main version string (e.g. "v2"), or None if not set.
-        """
         main_path = self._main_file(name)
         if not main_path.exists():
             return None