refactor: clarify naming and eliminate docstring duplication

Rename _get_run → _require_run in RunManager to distinguish it from
the public get_run (returns None). The "require" name makes the
KeyError-raising behavior obvious at call sites.

Move the shared returncode/timed_out field documentation from
RunResult and AgentResult into the base ProcessResult class where
it belongs, eliminating identical docstrings in both subclasses.

Co-authored-by: Ralphify <noreply@ralphify.co>

Author: 2 people

src/ralphify/_agent.py

@@ -46,12 +46,7 @@
 
 @dataclass
 class AgentResult(ProcessResult):
-    """Result of running the agent subprocess.
-
-    *returncode* is the process exit code, or ``None`` when the process
-    timed out.  *timed_out* makes the timeout condition explicit — prefer
-    checking ``timed_out`` over ``returncode is None``.
-    """
+    """Result of running the agent subprocess."""
 
     elapsed: float = 0.0
     log_file: Path | None = None

src/ralphify/_output.py

@@ -22,6 +22,10 @@ class ProcessResult:
     Shared by :class:`~ralphify._runner.RunResult` and
     :class:`~ralphify._agent.AgentResult` so the common *success*
     logic lives in one place.
+
+    *returncode* is the process exit code, or ``None`` when the process
+    timed out.  *timed_out* makes the timeout condition explicit — prefer
+    checking ``timed_out`` over ``returncode is None``.
     """
 
     returncode: int | None

src/ralphify/_runner.py

@@ -18,12 +18,7 @@
 
 @dataclass
 class RunResult(ProcessResult):
-    """Result of running a command or script.
-
-    *returncode* is the process exit code, or ``None`` when the process
-    timed out.  *timed_out* makes the timeout condition explicit — prefer
-    checking ``timed_out`` over ``returncode is None``.
-    """
+    """Result of running a command or script."""
 
     output: str = ""
 

src/ralphify/manager.py

@@ -67,7 +67,7 @@ def _lookup(self, run_id: str) -> ManagedRun:
         except KeyError:
             raise KeyError(f"No run with ID '{run_id}'") from None
 
-    def _get_run(self, run_id: str) -> ManagedRun:
+    def _require_run(self, run_id: str) -> ManagedRun:
         """Look up a run by ID under the lock. Raises ``KeyError`` if missing."""
         with self._lock:
             return self._lookup(run_id)
@@ -114,15 +114,15 @@ def start_run(self, run_id: str) -> None:
 
     def stop_run(self, run_id: str) -> None:
         """Signal the run to stop after the current iteration finishes."""
-        self._get_run(run_id).state.request_stop()
+        self._require_run(run_id).state.request_stop()
 
     def pause_run(self, run_id: str) -> None:
         """Pause the run between iterations until :meth:`resume_run` is called."""
-        self._get_run(run_id).state.request_pause()
+        self._require_run(run_id).state.request_pause()
 
     def resume_run(self, run_id: str) -> None:
         """Resume a paused run."""
-        self._get_run(run_id).state.request_resume()
+        self._require_run(run_id).state.request_resume()
 
     def list_runs(self) -> list[ManagedRun]:
         """Return a snapshot of all registered runs."""