Centralize paginated manager terminal status polling

cursoragent · shrisukhani · cursoragent · commit 5fba6920f1aa · 2026-02-14T12:57:20.000Z
Co-authored-by: Shri Sukhani &lt;shrisukhani@users.noreply.github.com&gt;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -101,6 +101,8 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_job_fetch_helper_boundary.py` (centralization boundary enforcement for retry/paginated-fetch helper primitives),
   - `tests/test_job_fetch_helper_usage.py` (shared retry/paginated-fetch defaults helper usage enforcement),
   - `tests/test_job_pagination_helper_usage.py` (shared scrape/crawl pagination helper usage enforcement),
+  - `tests/test_job_poll_helper_boundary.py` (centralization boundary enforcement for terminal-status polling helper primitives),
+  - `tests/test_job_poll_helper_usage.py` (shared terminal-status polling helper usage enforcement),
   - `tests/test_job_start_payload_helper_usage.py` (shared scrape/crawl start-payload helper usage enforcement),
   - `tests/test_job_wait_helper_boundary.py` (centralization boundary enforcement for wait-for-job helper primitives),
   - `tests/test_job_wait_helper_usage.py` (shared wait-for-job defaults helper usage enforcement),
diff --git a/hyperbrowser/client/managers/async_manager/crawl.py b/hyperbrowser/client/managers/async_manager/crawl.py
@@ -1,8 +1,8 @@
 from typing import Optional
 
 from hyperbrowser.models.consts import POLLING_ATTEMPTS
-from ...polling import (
-    poll_until_terminal_status_async,
+from ..job_poll_utils import (
+    poll_job_until_terminal_status_async as poll_until_terminal_status_async,
 )
 from ..job_fetch_utils import (
     collect_paginated_results_with_defaults_async,
diff --git a/hyperbrowser/client/managers/async_manager/scrape.py b/hyperbrowser/client/managers/async_manager/scrape.py
@@ -1,8 +1,8 @@
 from typing import Optional
 
 from hyperbrowser.models.consts import POLLING_ATTEMPTS
-from ...polling import (
-    poll_until_terminal_status_async,
+from ..job_poll_utils import (
+    poll_job_until_terminal_status_async as poll_until_terminal_status_async,
 )
 from ..job_fetch_utils import (
     collect_paginated_results_with_defaults_async,
diff --git a/hyperbrowser/client/managers/async_manager/web/batch_fetch.py b/hyperbrowser/client/managers/async_manager/web/batch_fetch.py
@@ -22,8 +22,8 @@
     read_page_current_batch,
     read_page_total_batches,
 )
-from ....polling import (
-    poll_until_terminal_status_async,
+from ...job_poll_utils import (
+    poll_job_until_terminal_status_async as poll_until_terminal_status_async,
 )
 from ...response_utils import parse_response_model
 from ...start_job_utils import build_started_job_context
diff --git a/hyperbrowser/client/managers/async_manager/web/crawl.py b/hyperbrowser/client/managers/async_manager/web/crawl.py
@@ -22,8 +22,8 @@
     read_page_current_batch,
     read_page_total_batches,
 )
-from ....polling import (
-    poll_until_terminal_status_async,
+from ...job_poll_utils import (
+    poll_job_until_terminal_status_async as poll_until_terminal_status_async,
 )
 from ...response_utils import parse_response_model
 from ...start_job_utils import build_started_job_context
diff --git a/hyperbrowser/client/managers/job_poll_utils.py b/hyperbrowser/client/managers/job_poll_utils.py
@@ -0,0 +1,41 @@
+from typing import Awaitable, Callable, Optional
+
+from ..polling import poll_until_terminal_status, poll_until_terminal_status_async
+
+
+def poll_job_until_terminal_status(
+    *,
+    operation_name: str,
+    get_status: Callable[[], str],
+    is_terminal_status: Callable[[str], bool],
+    poll_interval_seconds: float,
+    max_wait_seconds: Optional[float],
+    max_status_failures: int,
+) -> str:
+    return poll_until_terminal_status(
+        operation_name=operation_name,
+        get_status=get_status,
+        is_terminal_status=is_terminal_status,
+        poll_interval_seconds=poll_interval_seconds,
+        max_wait_seconds=max_wait_seconds,
+        max_status_failures=max_status_failures,
+    )
+
+
+async def poll_job_until_terminal_status_async(
+    *,
+    operation_name: str,
+    get_status: Callable[[], Awaitable[str]],
+    is_terminal_status: Callable[[str], bool],
+    poll_interval_seconds: float,
+    max_wait_seconds: Optional[float],
+    max_status_failures: int,
+) -> str:
+    return await poll_until_terminal_status_async(
+        operation_name=operation_name,
+        get_status=get_status,
+        is_terminal_status=is_terminal_status,
+        poll_interval_seconds=poll_interval_seconds,
+        max_wait_seconds=max_wait_seconds,
+        max_status_failures=max_status_failures,
+    )
diff --git a/hyperbrowser/client/managers/sync_manager/crawl.py b/hyperbrowser/client/managers/sync_manager/crawl.py
@@ -1,9 +1,7 @@
 from typing import Optional
 
 from hyperbrowser.models.consts import POLLING_ATTEMPTS
-from ...polling import (
-    poll_until_terminal_status,
-)
+from ..job_poll_utils import poll_job_until_terminal_status as poll_until_terminal_status
 from ..job_fetch_utils import (
     collect_paginated_results_with_defaults,
     fetch_job_result_with_defaults,
diff --git a/hyperbrowser/client/managers/sync_manager/scrape.py b/hyperbrowser/client/managers/sync_manager/scrape.py
@@ -1,9 +1,7 @@
 from typing import Optional
 
 from hyperbrowser.models.consts import POLLING_ATTEMPTS
-from ...polling import (
-    poll_until_terminal_status,
-)
+from ..job_poll_utils import poll_job_until_terminal_status as poll_until_terminal_status
 from ..job_fetch_utils import (
     collect_paginated_results_with_defaults,
     fetch_job_result_with_defaults,
diff --git a/hyperbrowser/client/managers/sync_manager/web/batch_fetch.py b/hyperbrowser/client/managers/sync_manager/web/batch_fetch.py
@@ -22,8 +22,8 @@
     read_page_current_batch,
     read_page_total_batches,
 )
-from ....polling import (
-    poll_until_terminal_status,
+from ...job_poll_utils import (
+    poll_job_until_terminal_status as poll_until_terminal_status,
 )
 from ...response_utils import parse_response_model
 from ...start_job_utils import build_started_job_context
diff --git a/hyperbrowser/client/managers/sync_manager/web/crawl.py b/hyperbrowser/client/managers/sync_manager/web/crawl.py
@@ -22,9 +22,7 @@
     read_page_current_batch,
     read_page_total_batches,
 )
-from ....polling import (
-    poll_until_terminal_status,
-)
+from ...job_poll_utils import poll_job_until_terminal_status as poll_until_terminal_status
 from ...response_utils import parse_response_model
 from ...start_job_utils import build_started_job_context
 
diff --git a/tests/test_architecture_marker_usage.py b/tests/test_architecture_marker_usage.py
@@ -41,6 +41,8 @@
     "tests/test_job_pagination_helper_usage.py",
     "tests/test_job_fetch_helper_boundary.py",
     "tests/test_job_fetch_helper_usage.py",
+    "tests/test_job_poll_helper_boundary.py",
+    "tests/test_job_poll_helper_usage.py",
     "tests/test_job_start_payload_helper_usage.py",
     "tests/test_job_wait_helper_boundary.py",
     "tests/test_job_wait_helper_usage.py",
diff --git a/tests/test_core_type_helper_usage.py b/tests/test_core_type_helper_usage.py
@@ -34,6 +34,7 @@
     "hyperbrowser/client/managers/extension_create_utils.py",
     "hyperbrowser/client/managers/extract_payload_utils.py",
     "hyperbrowser/client/managers/job_fetch_utils.py",
+    "hyperbrowser/client/managers/job_poll_utils.py",
     "hyperbrowser/client/managers/job_pagination_utils.py",
     "hyperbrowser/client/managers/job_start_payload_utils.py",
     "hyperbrowser/client/managers/page_params_utils.py",
diff --git a/tests/test_job_poll_helper_boundary.py b/tests/test_job_poll_helper_boundary.py
@@ -0,0 +1,27 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+MANAGERS_DIR = Path("hyperbrowser/client/managers")
+
+
+def test_poll_until_terminal_status_primitives_are_centralized():
+    violating_modules: list[str] = []
+    for module_path in sorted(MANAGERS_DIR.rglob("*.py")):
+        if module_path.name in {"__init__.py", "job_poll_utils.py"}:
+            continue
+        module_text = module_path.read_text(encoding="utf-8")
+        if (
+            "from ..polling import poll_until_terminal_status" in module_text
+            or "from ..polling import poll_until_terminal_status_async" in module_text
+            or "from ...polling import poll_until_terminal_status" in module_text
+            or "from ...polling import poll_until_terminal_status_async" in module_text
+            or "from ....polling import poll_until_terminal_status" in module_text
+            or "from ....polling import poll_until_terminal_status_async" in module_text
+        ):
+            violating_modules.append(module_path.as_posix())
+
+    assert violating_modules == []
diff --git a/tests/test_job_poll_helper_usage.py b/tests/test_job_poll_helper_usage.py
@@ -0,0 +1,46 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+SYNC_MODULES = (
+    "hyperbrowser/client/managers/sync_manager/scrape.py",
+    "hyperbrowser/client/managers/sync_manager/crawl.py",
+    "hyperbrowser/client/managers/sync_manager/web/batch_fetch.py",
+    "hyperbrowser/client/managers/sync_manager/web/crawl.py",
+)
+
+ASYNC_MODULES = (
+    "hyperbrowser/client/managers/async_manager/scrape.py",
+    "hyperbrowser/client/managers/async_manager/crawl.py",
+    "hyperbrowser/client/managers/async_manager/web/batch_fetch.py",
+    "hyperbrowser/client/managers/async_manager/web/crawl.py",
+)
+
+
+def test_sync_managers_use_job_poll_helpers():
+    for module_path in SYNC_MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        assert (
+            "poll_job_until_terminal_status as poll_until_terminal_status"
+            in module_text
+        )
+        assert "poll_until_terminal_status(" in module_text
+        assert "from ..polling import" not in module_text
+        assert "from ...polling import" not in module_text
+        assert "from ....polling import" not in module_text
+
+
+def test_async_managers_use_job_poll_helpers():
+    for module_path in ASYNC_MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        assert (
+            "poll_job_until_terminal_status_async as poll_until_terminal_status_async"
+            in module_text
+        )
+        assert "poll_until_terminal_status_async(" in module_text
+        assert "from ..polling import" not in module_text
+        assert "from ...polling import" not in module_text
+        assert "from ....polling import" not in module_text
diff --git a/tests/test_job_poll_utils.py b/tests/test_job_poll_utils.py
@@ -0,0 +1,65 @@
+import asyncio
+
+import hyperbrowser.client.managers.job_poll_utils as job_poll_utils
+
+
+def test_poll_job_until_terminal_status_forwards_arguments():
+    captured_kwargs = {}
+
+    def _fake_poll_until_terminal_status(**kwargs):
+        nonlocal captured_kwargs
+        captured_kwargs = kwargs
+        return "completed"
+
+    original_poll = job_poll_utils.poll_until_terminal_status
+    job_poll_utils.poll_until_terminal_status = _fake_poll_until_terminal_status
+    try:
+        result = job_poll_utils.poll_job_until_terminal_status(
+            operation_name="job poll",
+            get_status=lambda: "running",
+            is_terminal_status=lambda status: status == "completed",
+            poll_interval_seconds=2.5,
+            max_wait_seconds=20.0,
+            max_status_failures=4,
+        )
+    finally:
+        job_poll_utils.poll_until_terminal_status = original_poll
+
+    assert result == "completed"
+    assert captured_kwargs["operation_name"] == "job poll"
+    assert captured_kwargs["poll_interval_seconds"] == 2.5
+    assert captured_kwargs["max_wait_seconds"] == 20.0
+    assert captured_kwargs["max_status_failures"] == 4
+
+
+def test_poll_job_until_terminal_status_async_forwards_arguments():
+    captured_kwargs = {}
+
+    async def _fake_poll_until_terminal_status_async(**kwargs):
+        nonlocal captured_kwargs
+        captured_kwargs = kwargs
+        return "completed"
+
+    original_poll = job_poll_utils.poll_until_terminal_status_async
+    job_poll_utils.poll_until_terminal_status_async = (
+        _fake_poll_until_terminal_status_async
+    )
+    try:
+        result = asyncio.run(
+            job_poll_utils.poll_job_until_terminal_status_async(
+                operation_name="job poll",
+                get_status=lambda: asyncio.sleep(0, result="running"),
+                is_terminal_status=lambda status: status == "completed",
+                poll_interval_seconds=2.5,
+                max_wait_seconds=20.0,
+                max_status_failures=4,
+            )
+        )
+    finally:
+        job_poll_utils.poll_until_terminal_status_async = original_poll
+
+    assert result == "completed"
+    assert captured_kwargs["operation_name"] == "job poll"
+    assert captured_kwargs["poll_interval_seconds"] == 2.5
+    assert captured_kwargs["max_wait_seconds"] == 20.0
+    assert captured_kwargs["max_status_failures"] == 4

Original file line number	Diff line number	Diff line change
`@@ -22,8 +22,8 @@`
`22`	`22`	`read_page_current_batch,`
`23`	`23`	`read_page_total_batches,`
`24`	`24`	`)`
`25`		`-from ....polling import (`
`26`		`- poll_until_terminal_status_async,`
	`25`	`+from ...job_poll_utils import (`
	`26`	`+ poll_job_until_terminal_status_async as poll_until_terminal_status_async,`
`27`	`27`	`)`
`28`	`28`	`from ...response_utils import parse_response_model`
`29`	`29`	`from ...start_job_utils import build_started_job_context`