From 3c891f861bc06ebebd66d9ebeb8d3fef28c8571e Mon Sep 17 00:00:00 2001
From: Cody <cody@dkdc.io>
Date: Sun, 5 Apr 2026 23:43:40 -0400
Subject: [PATCH] fix(py): prefix Python error messages with variant tag for
 pattern matching

Users can now distinguish error types by matching on "[connection]",
"[request]", or "[empty_response]" prefixes in exception messages.
Type stubs updated to document which exceptions each function raises.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 crates/stringflow-py/src/lib.rs | 12 +++++++++---
 py/stringflow/core.pyi          | 17 +++++++++++++++--
 2 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/crates/stringflow-py/src/lib.rs b/crates/stringflow-py/src/lib.rs
index d031c1a..5e09f79 100644
--- a/crates/stringflow-py/src/lib.rs
+++ b/crates/stringflow-py/src/lib.rs
@@ -3,9 +3,15 @@ use pyo3::prelude::*;
 
 fn to_py_err(e: stringflow::Error) -> PyErr {
     match &e {
-        stringflow::Error::Unavailable(_) => PyErr::new::<PyConnectionError, _>(e.to_string()),
-        stringflow::Error::RequestFailed(_) => PyErr::new::<PyRuntimeError, _>(e.to_string()),
-        stringflow::Error::EmptyResponse => PyErr::new::<PyRuntimeError, _>(e.to_string()),
+        stringflow::Error::Unavailable(_) => {
+            PyErr::new::<PyConnectionError, _>(format!("[connection] {e}"))
+        }
+        stringflow::Error::RequestFailed(_) => {
+            PyErr::new::<PyRuntimeError, _>(format!("[request] {e}"))
+        }
+        stringflow::Error::EmptyResponse => {
+            PyErr::new::<PyRuntimeError, _>(format!("[empty_response] {e}"))
+        }
     }
 }
 
diff --git a/py/stringflow/core.pyi b/py/stringflow/core.pyi
index 85c5d9b..363d7f9 100644
--- a/py/stringflow/core.pyi
+++ b/py/stringflow/core.pyi
@@ -8,9 +8,22 @@ def chat(
     auth_header: str | None = None,
     auth_value: str | None = None,
 ) -> str:
-    """Low-level: send a chat request. Returns the response text."""
+    """Low-level: send a chat request. Returns the response text.
+
+    Raises:
+        ConnectionError: ``[connection] ...`` when the server is unreachable.
+        RuntimeError: ``[request] ...`` when the API returns an error, or
+            ``[empty_response] ...`` when the model returns no content.
+        ValueError: When *wire_format* is not a recognised format.
+    """
     ...
 
 def health_check(base_url: str) -> str:
-    """Low-level: send a health check. Returns the status string."""
+    """Low-level: send a health check. Returns the status string.
+
+    Raises:
+        ConnectionError: ``[connection] ...`` when the server is unreachable.
+        RuntimeError: ``[request] ...`` when the server returns an error, or
+            ``[empty_response] ...`` when the response has no content.
+    """
     ...