docs: add docstrings (#55)

Author: mtth

.pre-commit-config.yaml

@@ -12,4 +12,4 @@ repos:
         entry: poetry run poe fix
         language: system
         require_serial: true
-        types_or: [python, pyi, jupyter]
+        types: [python]

pyproject.toml

@@ -98,8 +98,15 @@ log_level = "DEBUG"
 line-length = 79
 
 [tool.ruff.lint]
-select = ["E", "F", "I"]
+select = ["D", "E", "F", "I"]
+ignore = ["D102", "D103", "D105", "D107", "D415"]
 
 [tool.ruff.lint.isort]
 force-sort-within-sections = true
 lines-after-imports = 2
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]

src/git_draft/__init__.py

@@ -1,3 +1,5 @@
+"""Git-friendly code assistant"""
+
 import logging
 
 from .bots import Action, Bot, Goal, Toolbox

src/git_draft/__main__.py

@@ -123,6 +123,8 @@ def callback(_option, _opt, _value, parser) -> None:
 
 
 class ToolPrinter(ToolVisitor):
+    """Visitor implementation which prints invocations to stdout"""
+
     def on_list_files(
         self, _paths: Sequence[PurePosixPath], _reason: str | None
     ) -> None:

src/git_draft/bots/common.py

@@ -1,3 +1,5 @@
+"""Shared bot utilities"""
+
 from __future__ import annotations
 
 import dataclasses
@@ -55,6 +57,7 @@ def state_folder_path(cls, ensure_exists=False) -> Path:
 
         Args:
             ensure_exists: Create the folder if it does not exist.
+
         """
         name = qualified_class_name(cls)
         path = ensure_state_home() / "bots" / name

src/git_draft/common.py

@@ -35,6 +35,8 @@ def ensure_state_home() -> Path:
 
 @dataclasses.dataclass(frozen=True)
 class Config:
+    """Overall CLI configuration"""
+
     log_level: int = logging.INFO
     auto_reset: bool = True
     bots: Sequence[BotConfig] = dataclasses.field(default_factory=lambda: [])
@@ -61,6 +63,8 @@ def load(cls) -> Self:
 
 @dataclasses.dataclass(frozen=True)
 class BotConfig:
+    """Individual bot configuration for CLI use"""
+
     factory: str
     name: str | None = None
     config: JSONObject | None = None

src/git_draft/drafter.py

@@ -1,3 +1,5 @@
+"""Git state management logic"""
+
 from __future__ import annotations
 
 import dataclasses

src/git_draft/prompt.py

@@ -21,6 +21,8 @@
 
 @dataclasses.dataclass(frozen=True)
 class TemplatedPrompt:
+    """A parametrized prompt"""
+
     template: str
     context: Mapping[str, str]
 
@@ -32,6 +34,7 @@ def parse(cls, name: str, *args: str) -> Self:
             name: The name of the template.
             *args: Additional arguments for context, expected in 'key=value'
                 format.
+
         """
         return cls(name, dict(e.split("=", 1) for e in args))
 
@@ -94,6 +97,8 @@ def _extract_preamble(source: str, env: jinja2.Environment) -> str | None:
 
 @dataclasses.dataclass(frozen=True)
 class Template:
+    """An available template"""
+
     rel_path: Path
     abs_path: Path
     source: str

src/git_draft/store.py

@@ -16,6 +16,8 @@
 
 
 class Store:
+    """Lightweight sqlite wrapper"""
+
     _name = "v1.sqlite3"
 
     def __init__(self, conn: sqlite3.Connection) -> None:
@@ -48,6 +50,7 @@ def cursor(self) -> Iterator[sqlite3.Cursor]:
 
 @functools.cache
 def sql(name: str) -> str:
+    """Loads a query from its name"""
     path = _query_root / f"{name}.sql"
     with open(path) as reader:
         return reader.read()

src/git_draft/toolbox.py

@@ -1,3 +1,5 @@
+"""Functionality available to bots"""
+
 from __future__ import annotations
 
 import logging
@@ -82,6 +84,8 @@ def _delete(self, path: PurePosixPath) -> bool:  # pragma: no cover
 
 
 class ToolVisitor(Protocol):
+    """Tool usage hook"""
+
     def on_list_files(
         self, paths: Sequence[PurePosixPath], reason: str | None
     ) -> None: ...  # pragma: no cover