Share extract start payload construction across managers

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

Author: cursoragent

CONTRIBUTING.md

@@ -90,6 +90,7 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_examples_naming_convention.py` (example sync/async prefix naming enforcement),
   - `tests/test_examples_syntax.py` (example script syntax guardrail),
   - `tests/test_extension_create_helper_usage.py` (extension create-input normalization helper usage enforcement),
+  - `tests/test_extract_payload_helper_usage.py` (extract start-payload helper usage enforcement),
   - `tests/test_guardrail_ast_utils.py` (shared AST guard utility contract),
   - `tests/test_job_pagination_helper_usage.py` (shared scrape/crawl pagination helper usage enforcement),
   - `tests/test_makefile_quality_targets.py` (Makefile quality-gate target enforcement),

hyperbrowser/client/managers/async_manager/extract.py

@@ -1,6 +1,5 @@
 from typing import Optional
 
-from hyperbrowser.exceptions import HyperbrowserError
 from hyperbrowser.models.consts import POLLING_ATTEMPTS
 from hyperbrowser.models.extract import (
     ExtractJobResponse,
@@ -13,8 +12,7 @@
     ensure_started_job_id,
     wait_for_job_result_async,
 )
-from ..serialization_utils import serialize_model_dump_to_dict
-from ...schema_utils import resolve_schema_input
+from ..extract_payload_utils import build_extract_start_payload
 from ..response_utils import parse_response_model
 
 
@@ -23,15 +21,7 @@ def __init__(self, client):
         self._client = client
 
     async def start(self, params: StartExtractJobParams) -> StartExtractJobResponse:
-        if not params.schema_ and not params.prompt:
-            raise HyperbrowserError("Either schema or prompt must be provided")
-
-        payload = serialize_model_dump_to_dict(
-            params,
-            error_message="Failed to serialize extract start params",
-        )
-        if params.schema_:
-            payload["schema"] = resolve_schema_input(params.schema_)
+        payload = build_extract_start_payload(params)
 
         response = await self._client.transport.post(
             self._client._build_url("/extract"),

hyperbrowser/client/managers/extract_payload_utils.py

@@ -0,0 +1,20 @@
+from typing import Any, Dict
+
+from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.models.extract import StartExtractJobParams
+
+from ..schema_utils import resolve_schema_input
+from .serialization_utils import serialize_model_dump_to_dict
+
+
+def build_extract_start_payload(params: StartExtractJobParams) -> Dict[str, Any]:
+    if not params.schema_ and not params.prompt:
+        raise HyperbrowserError("Either schema or prompt must be provided")
+
+    payload = serialize_model_dump_to_dict(
+        params,
+        error_message="Failed to serialize extract start params",
+    )
+    if params.schema_:
+        payload["schema"] = resolve_schema_input(params.schema_)
+    return payload

hyperbrowser/client/managers/sync_manager/extract.py

@@ -1,6 +1,5 @@
 from typing import Optional
 
-from hyperbrowser.exceptions import HyperbrowserError
 from hyperbrowser.models.consts import POLLING_ATTEMPTS
 from hyperbrowser.models.extract import (
     ExtractJobResponse,
@@ -9,8 +8,7 @@
     StartExtractJobResponse,
 )
 from ...polling import build_operation_name, ensure_started_job_id, wait_for_job_result
-from ..serialization_utils import serialize_model_dump_to_dict
-from ...schema_utils import resolve_schema_input
+from ..extract_payload_utils import build_extract_start_payload
 from ..response_utils import parse_response_model
 
 
@@ -19,15 +17,7 @@ def __init__(self, client):
         self._client = client
 
     def start(self, params: StartExtractJobParams) -> StartExtractJobResponse:
-        if not params.schema_ and not params.prompt:
-            raise HyperbrowserError("Either schema or prompt must be provided")
-
-        payload = serialize_model_dump_to_dict(
-            params,
-            error_message="Failed to serialize extract start params",
-        )
-        if params.schema_:
-            payload["schema"] = resolve_schema_input(params.schema_)
+        payload = build_extract_start_payload(params)
 
         response = self._client.transport.post(
             self._client._build_url("/extract"),

tests/test_architecture_marker_usage.py

@@ -31,6 +31,7 @@
     "tests/test_examples_syntax.py",
     "tests/test_docs_python3_commands.py",
     "tests/test_extension_create_helper_usage.py",
+    "tests/test_extract_payload_helper_usage.py",
     "tests/test_examples_naming_convention.py",
     "tests/test_job_pagination_helper_usage.py",
     "tests/test_example_sync_async_parity.py",

tests/test_extract_payload_helper_usage.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+MODULES = (
+    "hyperbrowser/client/managers/sync_manager/extract.py",
+    "hyperbrowser/client/managers/async_manager/extract.py",
+)
+
+
+def test_extract_managers_use_shared_extract_payload_helper():
+    for module_path in MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        assert "build_extract_start_payload(" in module_text
+        assert "Either schema or prompt must be provided" not in module_text
+        assert "serialize_model_dump_to_dict(" not in module_text
+        assert "resolve_schema_input(" not in module_text

tests/test_extract_payload_utils.py

@@ -0,0 +1,115 @@
+from types import MappingProxyType
+
+import pytest
+from pydantic import BaseModel
+
+import hyperbrowser.client.managers.extract_payload_utils as extract_payload_utils
+from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.models.extract import StartExtractJobParams
+
+
+def test_build_extract_start_payload_requires_schema_or_prompt():
+    params = StartExtractJobParams(urls=["https://example.com"])
+
+    with pytest.raises(HyperbrowserError, match="Either schema or prompt must be provided"):
+        extract_payload_utils.build_extract_start_payload(params)
+
+
+def test_build_extract_start_payload_serializes_prompt_payload():
+    params = StartExtractJobParams(
+        urls=["https://example.com"],
+        prompt="extract content",
+    )
+
+    payload = extract_payload_utils.build_extract_start_payload(params)
+
+    assert payload["urls"] == ["https://example.com"]
+    assert payload["prompt"] == "extract content"
+
+
+def test_build_extract_start_payload_resolves_schema_values(monkeypatch: pytest.MonkeyPatch):
+    class _SchemaModel(BaseModel):
+        title: str
+
+    params = StartExtractJobParams(
+        urls=["https://example.com"],
+        schema=_SchemaModel,
+    )
+
+    monkeypatch.setattr(
+        extract_payload_utils,
+        "resolve_schema_input",
+        lambda schema_input: {"resolvedSchema": schema_input.__name__},
+    )
+
+    payload = extract_payload_utils.build_extract_start_payload(params)
+
+    assert payload["schema"] == {"resolvedSchema": "_SchemaModel"}
+
+
+def test_build_extract_start_payload_wraps_serialization_errors(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    params = StartExtractJobParams(
+        urls=["https://example.com"],
+        prompt="extract content",
+    )
+
+    def _raise_model_dump_error(*args, **kwargs):
+        _ = args
+        _ = kwargs
+        raise RuntimeError("broken model_dump")
+
+    monkeypatch.setattr(StartExtractJobParams, "model_dump", _raise_model_dump_error)
+
+    with pytest.raises(
+        HyperbrowserError, match="Failed to serialize extract start params"
+    ) as exc_info:
+        extract_payload_utils.build_extract_start_payload(params)
+
+    assert isinstance(exc_info.value.original_error, RuntimeError)
+
+
+def test_build_extract_start_payload_preserves_hyperbrowser_serialization_errors(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    params = StartExtractJobParams(
+        urls=["https://example.com"],
+        prompt="extract content",
+    )
+
+    def _raise_model_dump_error(*args, **kwargs):
+        _ = args
+        _ = kwargs
+        raise HyperbrowserError("custom model_dump failure")
+
+    monkeypatch.setattr(StartExtractJobParams, "model_dump", _raise_model_dump_error)
+
+    with pytest.raises(
+        HyperbrowserError, match="custom model_dump failure"
+    ) as exc_info:
+        extract_payload_utils.build_extract_start_payload(params)
+
+    assert exc_info.value.original_error is None
+
+
+def test_build_extract_start_payload_rejects_non_dict_serialized_payload(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    params = StartExtractJobParams(
+        urls=["https://example.com"],
+        prompt="extract content",
+    )
+
+    monkeypatch.setattr(
+        StartExtractJobParams,
+        "model_dump",
+        lambda *args, **kwargs: MappingProxyType({"urls": ["https://example.com"]}),
+    )
+
+    with pytest.raises(
+        HyperbrowserError, match="Failed to serialize extract start params"
+    ) as exc_info:
+        extract_payload_utils.build_extract_start_payload(params)
+
+    assert exc_info.value.original_error is None