Add specialized timeout and polling exception types

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

hyperbrowser/client/polling.py

@@ -2,7 +2,11 @@
 import time
 from typing import Awaitable, Callable, Optional, TypeVar
 
-from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.exceptions import (
+    HyperbrowserError,
+    HyperbrowserPollingError,
+    HyperbrowserTimeoutError,
+)
 
 T = TypeVar("T")
 
@@ -27,7 +31,7 @@ def poll_until_terminal_status(
 
     while True:
         if has_exceeded_max_wait(start_time, max_wait_seconds):
-            raise HyperbrowserError(
+            raise HyperbrowserTimeoutError(
                 f"Timed out waiting for {operation_name} after {max_wait_seconds} seconds"
             )
 
@@ -37,7 +41,7 @@ def poll_until_terminal_status(
         except Exception as exc:
             failures += 1
             if failures >= max_status_failures:
-                raise HyperbrowserError(
+                raise HyperbrowserPollingError(
                     f"Failed to poll {operation_name} after {max_status_failures} attempts: {exc}"
                 ) from exc
             time.sleep(poll_interval_seconds)
@@ -82,7 +86,7 @@ async def poll_until_terminal_status_async(
 
     while True:
         if has_exceeded_max_wait(start_time, max_wait_seconds):
-            raise HyperbrowserError(
+            raise HyperbrowserTimeoutError(
                 f"Timed out waiting for {operation_name} after {max_wait_seconds} seconds"
             )
 
@@ -92,7 +96,7 @@ async def poll_until_terminal_status_async(
         except Exception as exc:
             failures += 1
             if failures >= max_status_failures:
-                raise HyperbrowserError(
+                raise HyperbrowserPollingError(
                     f"Failed to poll {operation_name} after {max_status_failures} attempts: {exc}"
                 ) from exc
             await asyncio.sleep(poll_interval_seconds)

hyperbrowser/exceptions.py

@@ -36,3 +36,11 @@ def __str__(self) -> str:
 
     def __repr__(self) -> str:
         return self.__str__()
+
+
+class HyperbrowserTimeoutError(HyperbrowserError):
+    """Raised when a polling or wait operation exceeds configured timeout."""
+
+
+class HyperbrowserPollingError(HyperbrowserError):
+    """Raised when a polling operation repeatedly fails to retrieve status."""

tests/test_polling.py

@@ -8,7 +8,11 @@
     retry_operation,
     retry_operation_async,
 )
-from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.exceptions import (
+    HyperbrowserError,
+    HyperbrowserPollingError,
+    HyperbrowserTimeoutError,
+)
 
 
 def test_poll_until_terminal_status_returns_terminal_value():
@@ -26,7 +30,9 @@ def test_poll_until_terminal_status_returns_terminal_value():
 
 
 def test_poll_until_terminal_status_times_out():
-    with pytest.raises(HyperbrowserError, match="Timed out waiting for sync timeout"):
+    with pytest.raises(
+        HyperbrowserTimeoutError, match="Timed out waiting for sync timeout"
+    ):
         poll_until_terminal_status(
             operation_name="sync timeout",
             get_status=lambda: "running",
@@ -57,7 +63,9 @@ def get_status() -> str:
 
 
 def test_poll_until_terminal_status_raises_after_status_failures():
-    with pytest.raises(HyperbrowserError, match="Failed to poll sync poll failure"):
+    with pytest.raises(
+        HyperbrowserPollingError, match="Failed to poll sync poll failure"
+    ):
         poll_until_terminal_status(
             operation_name="sync poll failure",
             get_status=lambda: (_ for _ in ()).throw(ValueError("always")),
@@ -149,3 +157,20 @@ async def get_status() -> str:
         assert status == "completed"
 
     asyncio.run(run())
+
+
+def test_async_poll_until_terminal_status_raises_after_status_failures():
+    async def run() -> None:
+        with pytest.raises(
+            HyperbrowserPollingError, match="Failed to poll async poll failure"
+        ):
+            await poll_until_terminal_status_async(
+                operation_name="async poll failure",
+                get_status=lambda: (_ for _ in ()).throw(ValueError("always")),
+                is_terminal_status=lambda value: value in {"completed", "failed"},
+                poll_interval_seconds=0.0001,
+                max_wait_seconds=1.0,
+                max_status_failures=2,
+            )
+
+    asyncio.run(run())