Centralize web manager operation metadata

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

Author: cursoragent

CONTRIBUTING.md

@@ -133,6 +133,7 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_started_job_helper_boundary.py` (centralization boundary enforcement for started-job helper primitives),
   - `tests/test_tool_mapping_reader_usage.py` (tools mapping-helper usage),
   - `tests/test_type_utils_usage.py` (type `__mro__` boundary centralization in `hyperbrowser/type_utils.py`),
+  - `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_route_constants_usage.py` (web manager route-constant usage enforcement).

hyperbrowser/client/managers/async_manager/web/batch_fetch.py

@@ -9,6 +9,7 @@
 )
 from ...page_params_utils import build_page_batch_params
 from ...job_status_utils import is_default_terminal_job_status
+from ...web_operation_metadata import BATCH_FETCH_OPERATION_METADATA
 from ...web_route_constants import BATCH_FETCH_JOB_ROUTE_PREFIX
 from ...web_payload_utils import build_batch_fetch_start_payload
 from ...web_payload_utils import build_batch_fetch_get_params
@@ -35,6 +36,7 @@
 
 
 class BatchFetchManager:
+    _OPERATION_METADATA = BATCH_FETCH_OPERATION_METADATA
     _ROUTE_PREFIX = BATCH_FETCH_JOB_ROUTE_PREFIX
 
     def __init__(self, client):
@@ -52,7 +54,7 @@ async def start(
         return parse_response_model(
             response.data,
             model=StartBatchFetchJobResponse,
-            operation_name="batch fetch start",
+            operation_name=self._OPERATION_METADATA.start_operation_name,
         )
 
     async def get_status(self, job_id: str) -> BatchFetchJobStatusResponse:
@@ -62,7 +64,7 @@ async def get_status(self, job_id: str) -> BatchFetchJobStatusResponse:
         return parse_response_model(
             response.data,
             model=BatchFetchJobStatusResponse,
-            operation_name="batch fetch status",
+            operation_name=self._OPERATION_METADATA.status_operation_name,
         )
 
     async def get(
@@ -76,7 +78,7 @@ async def get(
         return parse_response_model(
             response.data,
             model=BatchFetchJobResponse,
-            operation_name="batch fetch job",
+            operation_name=self._OPERATION_METADATA.job_operation_name,
         )
 
     async def start_and_wait(
@@ -90,8 +92,8 @@ async def start_and_wait(
         job_start_resp = await self.start(params)
         job_id, operation_name = build_started_job_context(
             started_job_id=job_start_resp.job_id,
-            start_error_message="Failed to start batch fetch job",
-            operation_name_prefix="batch fetch job ",
+            start_error_message=self._OPERATION_METADATA.start_error_message,
+            operation_name_prefix=self._OPERATION_METADATA.operation_name_prefix,
         )
 
         job_status = await poll_until_terminal_status_async(

hyperbrowser/client/managers/async_manager/web/crawl.py

@@ -9,6 +9,7 @@
 )
 from ...page_params_utils import build_page_batch_params
 from ...job_status_utils import is_default_terminal_job_status
+from ...web_operation_metadata import WEB_CRAWL_OPERATION_METADATA
 from ...web_route_constants import WEB_CRAWL_JOB_ROUTE_PREFIX
 from ...web_payload_utils import build_web_crawl_start_payload
 from ...web_payload_utils import build_web_crawl_get_params
@@ -35,6 +36,7 @@
 
 
 class WebCrawlManager:
+    _OPERATION_METADATA = WEB_CRAWL_OPERATION_METADATA
     _ROUTE_PREFIX = WEB_CRAWL_JOB_ROUTE_PREFIX
 
     def __init__(self, client):
@@ -50,7 +52,7 @@ async def start(self, params: StartWebCrawlJobParams) -> StartWebCrawlJobRespons
         return parse_response_model(
             response.data,
             model=StartWebCrawlJobResponse,
-            operation_name="web crawl start",
+            operation_name=self._OPERATION_METADATA.start_operation_name,
         )
 
     async def get_status(self, job_id: str) -> WebCrawlJobStatusResponse:
@@ -60,7 +62,7 @@ async def get_status(self, job_id: str) -> WebCrawlJobStatusResponse:
         return parse_response_model(
             response.data,
             model=WebCrawlJobStatusResponse,
-            operation_name="web crawl status",
+            operation_name=self._OPERATION_METADATA.status_operation_name,
         )
 
     async def get(
@@ -74,7 +76,7 @@ async def get(
         return parse_response_model(
             response.data,
             model=WebCrawlJobResponse,
-            operation_name="web crawl job",
+            operation_name=self._OPERATION_METADATA.job_operation_name,
         )
 
     async def start_and_wait(
@@ -88,8 +90,8 @@ async def start_and_wait(
         job_start_resp = await self.start(params)
         job_id, operation_name = build_started_job_context(
             started_job_id=job_start_resp.job_id,
-            start_error_message="Failed to start web crawl job",
-            operation_name_prefix="web crawl job ",
+            start_error_message=self._OPERATION_METADATA.start_error_message,
+            operation_name_prefix=self._OPERATION_METADATA.operation_name_prefix,
         )
 
         job_status = await poll_until_terminal_status_async(

hyperbrowser/client/managers/sync_manager/web/batch_fetch.py

@@ -9,6 +9,7 @@
 )
 from ...page_params_utils import build_page_batch_params
 from ...job_status_utils import is_default_terminal_job_status
+from ...web_operation_metadata import BATCH_FETCH_OPERATION_METADATA
 from ...web_route_constants import BATCH_FETCH_JOB_ROUTE_PREFIX
 from ...web_payload_utils import build_batch_fetch_start_payload
 from ...web_payload_utils import build_batch_fetch_get_params
@@ -35,6 +36,7 @@
 
 
 class BatchFetchManager:
+    _OPERATION_METADATA = BATCH_FETCH_OPERATION_METADATA
     _ROUTE_PREFIX = BATCH_FETCH_JOB_ROUTE_PREFIX
 
     def __init__(self, client):
@@ -50,7 +52,7 @@ def start(self, params: StartBatchFetchJobParams) -> StartBatchFetchJobResponse:
         return parse_response_model(
             response.data,
             model=StartBatchFetchJobResponse,
-            operation_name="batch fetch start",
+            operation_name=self._OPERATION_METADATA.start_operation_name,
         )
 
     def get_status(self, job_id: str) -> BatchFetchJobStatusResponse:
@@ -60,7 +62,7 @@ def get_status(self, job_id: str) -> BatchFetchJobStatusResponse:
         return parse_response_model(
             response.data,
             model=BatchFetchJobStatusResponse,
-            operation_name="batch fetch status",
+            operation_name=self._OPERATION_METADATA.status_operation_name,
         )
 
     def get(
@@ -74,7 +76,7 @@ def get(
         return parse_response_model(
             response.data,
             model=BatchFetchJobResponse,
-            operation_name="batch fetch job",
+            operation_name=self._OPERATION_METADATA.job_operation_name,
         )
 
     def start_and_wait(
@@ -88,8 +90,8 @@ def start_and_wait(
         job_start_resp = self.start(params)
         job_id, operation_name = build_started_job_context(
             started_job_id=job_start_resp.job_id,
-            start_error_message="Failed to start batch fetch job",
-            operation_name_prefix="batch fetch job ",
+            start_error_message=self._OPERATION_METADATA.start_error_message,
+            operation_name_prefix=self._OPERATION_METADATA.operation_name_prefix,
         )
 
         job_status = poll_until_terminal_status(

hyperbrowser/client/managers/sync_manager/web/crawl.py

@@ -9,6 +9,7 @@
 )
 from ...page_params_utils import build_page_batch_params
 from ...job_status_utils import is_default_terminal_job_status
+from ...web_operation_metadata import WEB_CRAWL_OPERATION_METADATA
 from ...web_route_constants import WEB_CRAWL_JOB_ROUTE_PREFIX
 from ...web_payload_utils import build_web_crawl_start_payload
 from ...web_payload_utils import build_web_crawl_get_params
@@ -33,6 +34,7 @@
 
 
 class WebCrawlManager:
+    _OPERATION_METADATA = WEB_CRAWL_OPERATION_METADATA
     _ROUTE_PREFIX = WEB_CRAWL_JOB_ROUTE_PREFIX
 
     def __init__(self, client):
@@ -48,7 +50,7 @@ def start(self, params: StartWebCrawlJobParams) -> StartWebCrawlJobResponse:
         return parse_response_model(
             response.data,
             model=StartWebCrawlJobResponse,
-            operation_name="web crawl start",
+            operation_name=self._OPERATION_METADATA.start_operation_name,
         )
 
     def get_status(self, job_id: str) -> WebCrawlJobStatusResponse:
@@ -58,7 +60,7 @@ def get_status(self, job_id: str) -> WebCrawlJobStatusResponse:
         return parse_response_model(
             response.data,
             model=WebCrawlJobStatusResponse,
-            operation_name="web crawl status",
+            operation_name=self._OPERATION_METADATA.status_operation_name,
         )
 
     def get(
@@ -72,7 +74,7 @@ def get(
         return parse_response_model(
             response.data,
             model=WebCrawlJobResponse,
-            operation_name="web crawl job",
+            operation_name=self._OPERATION_METADATA.job_operation_name,
         )
 
     def start_and_wait(
@@ -86,8 +88,8 @@ def start_and_wait(
         job_start_resp = self.start(params)
         job_id, operation_name = build_started_job_context(
             started_job_id=job_start_resp.job_id,
-            start_error_message="Failed to start web crawl job",
-            operation_name_prefix="web crawl job ",
+            start_error_message=self._OPERATION_METADATA.start_error_message,
+            operation_name_prefix=self._OPERATION_METADATA.operation_name_prefix,
         )
 
         job_status = poll_until_terminal_status(

hyperbrowser/client/managers/web_operation_metadata.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class WebOperationMetadata:
+    start_operation_name: str
+    status_operation_name: str
+    job_operation_name: str
+    start_error_message: str
+    operation_name_prefix: str
+
+
+BATCH_FETCH_OPERATION_METADATA = WebOperationMetadata(
+    start_operation_name="batch fetch start",
+    status_operation_name="batch fetch status",
+    job_operation_name="batch fetch job",
+    start_error_message="Failed to start batch fetch job",
+    operation_name_prefix="batch fetch job ",
+)
+
+WEB_CRAWL_OPERATION_METADATA = WebOperationMetadata(
+    start_operation_name="web crawl start",
+    status_operation_name="web crawl status",
+    job_operation_name="web crawl job",
+    start_error_message="Failed to start web crawl job",
+    operation_name_prefix="web crawl job ",
+)

tests/test_architecture_marker_usage.py

@@ -63,6 +63,7 @@
     "tests/test_start_and_wait_default_constants_usage.py",
     "tests/test_start_job_context_helper_usage.py",
     "tests/test_started_job_helper_boundary.py",
+    "tests/test_web_operation_metadata_usage.py",
     "tests/test_web_pagination_internal_reuse.py",
     "tests/test_web_payload_helper_usage.py",
     "tests/test_web_route_constants_usage.py",

tests/test_core_type_helper_usage.py

@@ -48,6 +48,7 @@
     "hyperbrowser/client/managers/polling_defaults.py",
     "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_route_constants.py",
     "hyperbrowser/client/managers/web_pagination_utils.py",
     "hyperbrowser/client/managers/web_payload_utils.py",

tests/test_web_operation_metadata.py

@@ -0,0 +1,26 @@
+from hyperbrowser.client.managers.web_operation_metadata import (
+    BATCH_FETCH_OPERATION_METADATA,
+    WEB_CRAWL_OPERATION_METADATA,
+)
+
+
+def test_batch_fetch_operation_metadata_values():
+    assert BATCH_FETCH_OPERATION_METADATA.start_operation_name == "batch fetch start"
+    assert BATCH_FETCH_OPERATION_METADATA.status_operation_name == "batch fetch status"
+    assert BATCH_FETCH_OPERATION_METADATA.job_operation_name == "batch fetch job"
+    assert (
+        BATCH_FETCH_OPERATION_METADATA.start_error_message
+        == "Failed to start batch fetch job"
+    )
+    assert BATCH_FETCH_OPERATION_METADATA.operation_name_prefix == "batch fetch job "
+
+
+def test_web_crawl_operation_metadata_values():
+    assert WEB_CRAWL_OPERATION_METADATA.start_operation_name == "web crawl start"
+    assert WEB_CRAWL_OPERATION_METADATA.status_operation_name == "web crawl status"
+    assert WEB_CRAWL_OPERATION_METADATA.job_operation_name == "web crawl job"
+    assert (
+        WEB_CRAWL_OPERATION_METADATA.start_error_message
+        == "Failed to start web crawl job"
+    )
+    assert WEB_CRAWL_OPERATION_METADATA.operation_name_prefix == "web crawl job "

tests/test_web_operation_metadata_usage.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+MODULES = (
+    "hyperbrowser/client/managers/sync_manager/web/batch_fetch.py",
+    "hyperbrowser/client/managers/async_manager/web/batch_fetch.py",
+    "hyperbrowser/client/managers/sync_manager/web/crawl.py",
+    "hyperbrowser/client/managers/async_manager/web/crawl.py",
+)
+
+
+def test_web_managers_use_shared_operation_metadata():
+    for module_path in MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        assert "web_operation_metadata import" in module_text
+        assert "_OPERATION_METADATA = " in module_text
+        assert "operation_name=self._OPERATION_METADATA." in module_text
+        assert "start_error_message=self._OPERATION_METADATA." in module_text
+        assert "operation_name_prefix=self._OPERATION_METADATA." in module_text
+        assert 'operation_name="' not in module_text
+        assert 'start_error_message="' not in module_text
+        assert 'operation_name_prefix="' not in module_text