Centralize shared web request execution helpers

cursoragent · shrisukhani · cursoragent · commit 10184ea0aef2 · 2026-02-14T14:39:26.000Z
Co-authored-by: Shri Sukhani &lt;shrisukhani@users.noreply.github.com&gt;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -138,6 +138,7 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_web_operation_metadata_usage.py` (web manager operation-metadata usage enforcement),
   - `tests/test_web_pagination_internal_reuse.py` (web pagination helper internal reuse of shared job pagination helpers),
   - `tests/test_web_payload_helper_usage.py` (web manager payload-helper usage enforcement),
+  - `tests/test_web_request_helper_usage.py` (web manager request-helper usage enforcement),
   - `tests/test_web_route_constants_usage.py` (web manager route-constant usage enforcement).
 
 ## Code quality conventions
diff --git a/hyperbrowser/client/managers/async_manager/web/batch_fetch.py b/hyperbrowser/client/managers/async_manager/web/batch_fetch.py
@@ -31,7 +31,11 @@
     DEFAULT_POLLING_RETRY_ATTEMPTS,
     DEFAULT_POLL_INTERVAL_SECONDS,
 )
-from ...response_utils import parse_response_model
+from ...web_request_utils import (
+    get_web_job_async,
+    get_web_job_status_async,
+    start_web_job_async,
+)
 from ...start_job_utils import build_started_job_context
 
 
@@ -46,23 +50,19 @@ async def start(
         self, params: StartBatchFetchJobParams
     ) -> StartBatchFetchJobResponse:
         payload = build_batch_fetch_start_payload(params)
-
-        response = await self._client.transport.post(
-            self._client._build_url(self._ROUTE_PREFIX),
-            data=payload,
-        )
-        return parse_response_model(
-            response.data,
+        return await start_web_job_async(
+            client=self._client,
+            route_prefix=self._ROUTE_PREFIX,
+            payload=payload,
             model=StartBatchFetchJobResponse,
             operation_name=self._OPERATION_METADATA.start_operation_name,
         )
 
     async def get_status(self, job_id: str) -> BatchFetchJobStatusResponse:
-        response = await self._client.transport.get(
-            self._client._build_url(f"{self._ROUTE_PREFIX}/{job_id}/status")
-        )
-        return parse_response_model(
-            response.data,
+        return await get_web_job_status_async(
+            client=self._client,
+            route_prefix=self._ROUTE_PREFIX,
+            job_id=job_id,
             model=BatchFetchJobStatusResponse,
             operation_name=self._OPERATION_METADATA.status_operation_name,
         )
@@ -71,12 +71,11 @@ async def get(
         self, job_id: str, params: Optional[GetBatchFetchJobParams] = None
     ) -> BatchFetchJobResponse:
         query_params = build_batch_fetch_get_params(params)
-        response = await self._client.transport.get(
-            self._client._build_url(f"{self._ROUTE_PREFIX}/{job_id}"),
+        return await get_web_job_async(
+            client=self._client,
+            route_prefix=self._ROUTE_PREFIX,
+            job_id=job_id,
             params=query_params,
-        )
-        return parse_response_model(
-            response.data,
             model=BatchFetchJobResponse,
             operation_name=self._OPERATION_METADATA.job_operation_name,
         )
diff --git a/hyperbrowser/client/managers/async_manager/web/crawl.py b/hyperbrowser/client/managers/async_manager/web/crawl.py
@@ -31,7 +31,11 @@
     DEFAULT_POLLING_RETRY_ATTEMPTS,
     DEFAULT_POLL_INTERVAL_SECONDS,
 )
-from ...response_utils import parse_response_model
+from ...web_request_utils import (
+    get_web_job_async,
+    get_web_job_status_async,
+    start_web_job_async,
+)
 from ...start_job_utils import build_started_job_context
 
 
@@ -44,23 +48,19 @@ def __init__(self, client):
 
     async def start(self, params: StartWebCrawlJobParams) -> StartWebCrawlJobResponse:
         payload = build_web_crawl_start_payload(params)
-
-        response = await self._client.transport.post(
-            self._client._build_url(self._ROUTE_PREFIX),
-            data=payload,
-        )
-        return parse_response_model(
-            response.data,
+        return await start_web_job_async(
+            client=self._client,
+            route_prefix=self._ROUTE_PREFIX,
+            payload=payload,
             model=StartWebCrawlJobResponse,
             operation_name=self._OPERATION_METADATA.start_operation_name,
         )
 
     async def get_status(self, job_id: str) -> WebCrawlJobStatusResponse:
-        response = await self._client.transport.get(
-            self._client._build_url(f"{self._ROUTE_PREFIX}/{job_id}/status")
-        )
-        return parse_response_model(
-            response.data,
+        return await get_web_job_status_async(
+            client=self._client,
+            route_prefix=self._ROUTE_PREFIX,
+            job_id=job_id,
             model=WebCrawlJobStatusResponse,
             operation_name=self._OPERATION_METADATA.status_operation_name,
         )
@@ -69,12 +69,11 @@ async def get(
         self, job_id: str, params: Optional[GetWebCrawlJobParams] = None
     ) -> WebCrawlJobResponse:
         query_params = build_web_crawl_get_params(params)
-        response = await self._client.transport.get(
-            self._client._build_url(f"{self._ROUTE_PREFIX}/{job_id}"),
+        return await get_web_job_async(
+            client=self._client,
+            route_prefix=self._ROUTE_PREFIX,
+            job_id=job_id,
             params=query_params,
-        )
-        return parse_response_model(
-            response.data,
             model=WebCrawlJobResponse,
             operation_name=self._OPERATION_METADATA.job_operation_name,
         )
diff --git a/hyperbrowser/client/managers/sync_manager/web/batch_fetch.py b/hyperbrowser/client/managers/sync_manager/web/batch_fetch.py
@@ -31,7 +31,7 @@
     DEFAULT_POLLING_RETRY_ATTEMPTS,
     DEFAULT_POLL_INTERVAL_SECONDS,
 )
-from ...response_utils import parse_response_model
+from ...web_request_utils import get_web_job, get_web_job_status, start_web_job
 from ...start_job_utils import build_started_job_context
 
 
@@ -44,23 +44,19 @@ def __init__(self, client):
 
     def start(self, params: StartBatchFetchJobParams) -> StartBatchFetchJobResponse:
         payload = build_batch_fetch_start_payload(params)
-
-        response = self._client.transport.post(
-            self._client._build_url(self._ROUTE_PREFIX),
-            data=payload,
-        )
-        return parse_response_model(
-            response.data,
+        return start_web_job(
+            client=self._client,
+            route_prefix=self._ROUTE_PREFIX,
+            payload=payload,
             model=StartBatchFetchJobResponse,
             operation_name=self._OPERATION_METADATA.start_operation_name,
         )
 
     def get_status(self, job_id: str) -> BatchFetchJobStatusResponse:
-        response = self._client.transport.get(
-            self._client._build_url(f"{self._ROUTE_PREFIX}/{job_id}/status")
-        )
-        return parse_response_model(
-            response.data,
+        return get_web_job_status(
+            client=self._client,
+            route_prefix=self._ROUTE_PREFIX,
+            job_id=job_id,
             model=BatchFetchJobStatusResponse,
             operation_name=self._OPERATION_METADATA.status_operation_name,
         )
@@ -69,12 +65,11 @@ def get(
         self, job_id: str, params: Optional[GetBatchFetchJobParams] = None
     ) -> BatchFetchJobResponse:
         query_params = build_batch_fetch_get_params(params)
-        response = self._client.transport.get(
-            self._client._build_url(f"{self._ROUTE_PREFIX}/{job_id}"),
+        return get_web_job(
+            client=self._client,
+            route_prefix=self._ROUTE_PREFIX,
+            job_id=job_id,
             params=query_params,
-        )
-        return parse_response_model(
-            response.data,
             model=BatchFetchJobResponse,
             operation_name=self._OPERATION_METADATA.job_operation_name,
         )
diff --git a/hyperbrowser/client/managers/sync_manager/web/crawl.py b/hyperbrowser/client/managers/sync_manager/web/crawl.py
@@ -29,7 +29,7 @@
     DEFAULT_POLLING_RETRY_ATTEMPTS,
     DEFAULT_POLL_INTERVAL_SECONDS,
 )
-from ...response_utils import parse_response_model
+from ...web_request_utils import get_web_job, get_web_job_status, start_web_job
 from ...start_job_utils import build_started_job_context
 
 
@@ -42,23 +42,19 @@ def __init__(self, client):
 
     def start(self, params: StartWebCrawlJobParams) -> StartWebCrawlJobResponse:
         payload = build_web_crawl_start_payload(params)
-
-        response = self._client.transport.post(
-            self._client._build_url(self._ROUTE_PREFIX),
-            data=payload,
-        )
-        return parse_response_model(
-            response.data,
+        return start_web_job(
+            client=self._client,
+            route_prefix=self._ROUTE_PREFIX,
+            payload=payload,
             model=StartWebCrawlJobResponse,
             operation_name=self._OPERATION_METADATA.start_operation_name,
         )
 
     def get_status(self, job_id: str) -> WebCrawlJobStatusResponse:
-        response = self._client.transport.get(
-            self._client._build_url(f"{self._ROUTE_PREFIX}/{job_id}/status")
-        )
-        return parse_response_model(
-            response.data,
+        return get_web_job_status(
+            client=self._client,
+            route_prefix=self._ROUTE_PREFIX,
+            job_id=job_id,
             model=WebCrawlJobStatusResponse,
             operation_name=self._OPERATION_METADATA.status_operation_name,
         )
@@ -67,12 +63,11 @@ def get(
         self, job_id: str, params: Optional[GetWebCrawlJobParams] = None
     ) -> WebCrawlJobResponse:
         query_params = build_web_crawl_get_params(params)
-        response = self._client.transport.get(
-            self._client._build_url(f"{self._ROUTE_PREFIX}/{job_id}"),
+        return get_web_job(
+            client=self._client,
+            route_prefix=self._ROUTE_PREFIX,
+            job_id=job_id,
             params=query_params,
-        )
-        return parse_response_model(
-            response.data,
             model=WebCrawlJobResponse,
             operation_name=self._OPERATION_METADATA.job_operation_name,
         )
diff --git a/hyperbrowser/client/managers/web_request_utils.py b/hyperbrowser/client/managers/web_request_utils.py
@@ -0,0 +1,119 @@
+from typing import Any, Dict, Optional, Type, TypeVar
+
+from .response_utils import parse_response_model
+
+T = TypeVar("T")
+
+
+def start_web_job(
+    *,
+    client: Any,
+    route_prefix: str,
+    payload: Dict[str, Any],
+    model: Type[T],
+    operation_name: str,
+) -> T:
+    response = client.transport.post(
+        client._build_url(route_prefix),
+        data=payload,
+    )
+    return parse_response_model(
+        response.data,
+        model=model,
+        operation_name=operation_name,
+    )
+
+
+def get_web_job_status(
+    *,
+    client: Any,
+    route_prefix: str,
+    job_id: str,
+    model: Type[T],
+    operation_name: str,
+) -> T:
+    response = client.transport.get(
+        client._build_url(f"{route_prefix}/{job_id}/status"),
+    )
+    return parse_response_model(
+        response.data,
+        model=model,
+        operation_name=operation_name,
+    )
+
+
+def get_web_job(
+    *,
+    client: Any,
+    route_prefix: str,
+    job_id: str,
+    params: Optional[Dict[str, Any]],
+    model: Type[T],
+    operation_name: str,
+) -> T:
+    response = client.transport.get(
+        client._build_url(f"{route_prefix}/{job_id}"),
+        params=params,
+    )
+    return parse_response_model(
+        response.data,
+        model=model,
+        operation_name=operation_name,
+    )
+
+
+async def start_web_job_async(
+    *,
+    client: Any,
+    route_prefix: str,
+    payload: Dict[str, Any],
+    model: Type[T],
+    operation_name: str,
+) -> T:
+    response = await client.transport.post(
+        client._build_url(route_prefix),
+        data=payload,
+    )
+    return parse_response_model(
+        response.data,
+        model=model,
+        operation_name=operation_name,
+    )
+
+
+async def get_web_job_status_async(
+    *,
+    client: Any,
+    route_prefix: str,
+    job_id: str,
+    model: Type[T],
+    operation_name: str,
+) -> T:
+    response = await client.transport.get(
+        client._build_url(f"{route_prefix}/{job_id}/status"),
+    )
+    return parse_response_model(
+        response.data,
+        model=model,
+        operation_name=operation_name,
+    )
+
+
+async def get_web_job_async(
+    *,
+    client: Any,
+    route_prefix: str,
+    job_id: str,
+    params: Optional[Dict[str, Any]],
+    model: Type[T],
+    operation_name: str,
+) -> T:
+    response = await client.transport.get(
+        client._build_url(f"{route_prefix}/{job_id}"),
+        params=params,
+    )
+    return parse_response_model(
+        response.data,
+        model=model,
+        operation_name=operation_name,
+    )
diff --git a/tests/test_architecture_marker_usage.py b/tests/test_architecture_marker_usage.py
@@ -68,6 +68,7 @@
     "tests/test_web_operation_metadata_usage.py",
     "tests/test_web_pagination_internal_reuse.py",
     "tests/test_web_payload_helper_usage.py",
+    "tests/test_web_request_helper_usage.py",
     "tests/test_web_route_constants_usage.py",
 )
 
diff --git a/tests/test_core_type_helper_usage.py b/tests/test_core_type_helper_usage.py
@@ -51,6 +51,7 @@
     "hyperbrowser/client/managers/session_upload_utils.py",
     "hyperbrowser/client/managers/session_profile_update_utils.py",
     "hyperbrowser/client/managers/web_operation_metadata.py",
+    "hyperbrowser/client/managers/web_request_utils.py",
     "hyperbrowser/client/managers/web_route_constants.py",
     "hyperbrowser/client/managers/web_pagination_utils.py",
     "hyperbrowser/client/managers/web_payload_utils.py",
diff --git a/tests/test_web_request_helper_usage.py b/tests/test_web_request_helper_usage.py
diff --git a/tests/test_web_request_utils.py b/tests/test_web_request_utils.py
diff --git a/tests/test_web_route_constants_usage.py b/tests/test_web_route_constants_usage.py

Original file line number	Diff line number	Diff line change
`@@ -68,6 +68,7 @@`
`68`	`68`	`"tests/test_web_operation_metadata_usage.py",`
`69`	`69`	`"tests/test_web_pagination_internal_reuse.py",`
`70`	`70`	`"tests/test_web_payload_helper_usage.py",`
	`71`	`+ "tests/test_web_request_helper_usage.py",`
`71`	`72`	`"tests/test_web_route_constants_usage.py",`
`72`	`73`	`)`
`73`	`74`