Unify optional query serialization with default helper

cursoragent · shrisukhani · cursoragent · commit ddd7691f35c4 · 2026-02-14T10:24:07.000Z
Co-authored-by: Shri Sukhani &lt;shrisukhani@users.noreply.github.com&gt;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -81,6 +81,7 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_computer_action_endpoint_helper_usage.py` (computer-action endpoint-normalization helper usage enforcement),
   - `tests/test_contributing_architecture_guard_listing.py` (`CONTRIBUTING.md` architecture-guard inventory completeness enforcement),
   - `tests/test_core_type_helper_usage.py` (core transport/config/header/file/polling/session/error/parsing manager+tool module enforcement of shared plain-type helper usage),
+  - `tests/test_default_serialization_helper_usage.py` (default optional-query serialization helper usage enforcement),
   - `tests/test_display_helper_usage.py` (display/key-format helper usage),
   - `tests/test_docs_python3_commands.py` (`README`/`CONTRIBUTING`/examples python3 command consistency enforcement),
   - `tests/test_example_run_instructions.py` (example run-instruction consistency enforcement),
diff --git a/hyperbrowser/client/managers/async_manager/crawl.py b/hyperbrowser/client/managers/async_manager/crawl.py
@@ -9,7 +9,10 @@
     poll_until_terminal_status_async,
     retry_operation_async,
 )
-from ..serialization_utils import serialize_model_dump_to_dict
+from ..serialization_utils import (
+    serialize_model_dump_or_default,
+    serialize_model_dump_to_dict,
+)
 from ..response_utils import parse_response_model
 from ....models.crawl import (
     CrawlJobResponse,
@@ -52,9 +55,9 @@ async def get_status(self, job_id: str) -> CrawlJobStatusResponse:
     async def get(
         self, job_id: str, params: Optional[GetCrawlJobParams] = None
     ) -> CrawlJobResponse:
-        params_obj = params or GetCrawlJobParams()
-        query_params = serialize_model_dump_to_dict(
-            params_obj,
+        query_params = serialize_model_dump_or_default(
+            params,
+            default_factory=GetCrawlJobParams,
             error_message="Failed to serialize crawl get params",
         )
         response = await self._client.transport.get(
diff --git a/hyperbrowser/client/managers/async_manager/profile.py b/hyperbrowser/client/managers/async_manager/profile.py
@@ -9,7 +9,7 @@
 )
 from hyperbrowser.models.session import BasicResponse
 from ..serialization_utils import (
-    serialize_model_dump_to_dict,
+    serialize_model_dump_or_default,
     serialize_optional_model_dump_to_dict,
 )
 from ..response_utils import parse_response_model
@@ -59,9 +59,9 @@ async def delete(self, id: str) -> BasicResponse:
     async def list(
         self, params: Optional[ProfileListParams] = None
     ) -> ProfileListResponse:
-        params_obj = params or ProfileListParams()
-        query_params = serialize_model_dump_to_dict(
-            params_obj,
+        query_params = serialize_model_dump_or_default(
+            params,
+            default_factory=ProfileListParams,
             error_message="Failed to serialize profile list params",
         )
         response = await self._client.transport.get(
diff --git a/hyperbrowser/client/managers/async_manager/scrape.py b/hyperbrowser/client/managers/async_manager/scrape.py
@@ -10,7 +10,10 @@
     retry_operation_async,
     wait_for_job_result_async,
 )
-from ..serialization_utils import serialize_model_dump_to_dict
+from ..serialization_utils import (
+    serialize_model_dump_or_default,
+    serialize_model_dump_to_dict,
+)
 from ..response_utils import parse_response_model
 from ....models.scrape import (
     BatchScrapeJobResponse,
@@ -59,9 +62,9 @@ async def get_status(self, job_id: str) -> BatchScrapeJobStatusResponse:
     async def get(
         self, job_id: str, params: Optional[GetBatchScrapeJobParams] = None
     ) -> BatchScrapeJobResponse:
-        params_obj = params or GetBatchScrapeJobParams()
-        query_params = serialize_model_dump_to_dict(
-            params_obj,
+        query_params = serialize_model_dump_or_default(
+            params,
+            default_factory=GetBatchScrapeJobParams,
             error_message="Failed to serialize batch scrape get params",
         )
         response = await self._client.transport.get(
diff --git a/hyperbrowser/client/managers/async_manager/session.py b/hyperbrowser/client/managers/async_manager/session.py
@@ -3,6 +3,7 @@
 import warnings
 from hyperbrowser.exceptions import HyperbrowserError
 from ..serialization_utils import (
+    serialize_model_dump_or_default,
     serialize_model_dump_to_dict,
     serialize_optional_model_dump_to_dict,
 )
@@ -38,9 +39,9 @@ async def list(
         session_id: str,
         params: Optional[SessionEventLogListParams] = None,
     ) -> SessionEventLogListResponse:
-        params_obj = params or SessionEventLogListParams()
-        query_params = serialize_model_dump_to_dict(
-            params_obj,
+        query_params = serialize_model_dump_or_default(
+            params,
+            default_factory=SessionEventLogListParams,
             error_message="Failed to serialize session event log params",
         )
         response = await self._client.transport.get(
@@ -81,9 +82,9 @@ async def create(
     async def get(
         self, id: str, params: Optional[SessionGetParams] = None
     ) -> SessionDetail:
-        params_obj = params or SessionGetParams()
-        query_params = serialize_model_dump_to_dict(
-            params_obj,
+        query_params = serialize_model_dump_or_default(
+            params,
+            default_factory=SessionGetParams,
             error_message="Failed to serialize session get params",
         )
         response = await self._client.transport.get(
@@ -109,9 +110,9 @@ async def stop(self, id: str) -> BasicResponse:
     async def list(
         self, params: Optional[SessionListParams] = None
     ) -> SessionListResponse:
-        params_obj = params or SessionListParams()
-        query_params = serialize_model_dump_to_dict(
-            params_obj,
+        query_params = serialize_model_dump_or_default(
+            params,
+            default_factory=SessionListParams,
             error_message="Failed to serialize session list params",
         )
         response = await self._client.transport.get(
diff --git a/hyperbrowser/client/managers/serialization_utils.py b/hyperbrowser/client/managers/serialization_utils.py
@@ -1,7 +1,9 @@
-from typing import Any, Dict
+from typing import Any, Callable, Dict, Optional, TypeVar
 
 from hyperbrowser.exceptions import HyperbrowserError
 
+T = TypeVar("T")
+
 
 def serialize_model_dump_to_dict(
     model: Any,
@@ -39,3 +41,20 @@ def serialize_optional_model_dump_to_dict(
         exclude_none=exclude_none,
         by_alias=by_alias,
     )
+
+
+def serialize_model_dump_or_default(
+    model: Optional[T],
+    *,
+    default_factory: Callable[[], T],
+    error_message: str,
+    exclude_none: bool = True,
+    by_alias: bool = True,
+) -> Dict[str, Any]:
+    model_obj = model if model is not None else default_factory()
+    return serialize_model_dump_to_dict(
+        model_obj,
+        error_message=error_message,
+        exclude_none=exclude_none,
+        by_alias=by_alias,
+    )
diff --git a/hyperbrowser/client/managers/sync_manager/crawl.py b/hyperbrowser/client/managers/sync_manager/crawl.py
@@ -9,7 +9,10 @@
     poll_until_terminal_status,
     retry_operation,
 )
-from ..serialization_utils import serialize_model_dump_to_dict
+from ..serialization_utils import (
+    serialize_model_dump_or_default,
+    serialize_model_dump_to_dict,
+)
 from ..response_utils import parse_response_model
 from ....models.crawl import (
     CrawlJobResponse,
@@ -52,9 +55,9 @@ def get_status(self, job_id: str) -> CrawlJobStatusResponse:
     def get(
         self, job_id: str, params: Optional[GetCrawlJobParams] = None
     ) -> CrawlJobResponse:
-        params_obj = params or GetCrawlJobParams()
-        query_params = serialize_model_dump_to_dict(
-            params_obj,
+        query_params = serialize_model_dump_or_default(
+            params,
+            default_factory=GetCrawlJobParams,
             error_message="Failed to serialize crawl get params",
         )
         response = self._client.transport.get(
diff --git a/hyperbrowser/client/managers/sync_manager/profile.py b/hyperbrowser/client/managers/sync_manager/profile.py
@@ -9,7 +9,7 @@
 )
 from hyperbrowser.models.session import BasicResponse
 from ..serialization_utils import (
-    serialize_model_dump_to_dict,
+    serialize_model_dump_or_default,
     serialize_optional_model_dump_to_dict,
 )
 from ..response_utils import parse_response_model
@@ -57,9 +57,9 @@ def delete(self, id: str) -> BasicResponse:
         )
 
     def list(self, params: Optional[ProfileListParams] = None) -> ProfileListResponse:
-        params_obj = params or ProfileListParams()
-        query_params = serialize_model_dump_to_dict(
-            params_obj,
+        query_params = serialize_model_dump_or_default(
+            params,
+            default_factory=ProfileListParams,
             error_message="Failed to serialize profile list params",
         )
         response = self._client.transport.get(
diff --git a/hyperbrowser/client/managers/sync_manager/scrape.py b/hyperbrowser/client/managers/sync_manager/scrape.py
@@ -10,7 +10,10 @@
     retry_operation,
     wait_for_job_result,
 )
-from ..serialization_utils import serialize_model_dump_to_dict
+from ..serialization_utils import (
+    serialize_model_dump_or_default,
+    serialize_model_dump_to_dict,
+)
 from ..response_utils import parse_response_model
 from ....models.scrape import (
     BatchScrapeJobResponse,
@@ -57,9 +60,9 @@ def get_status(self, job_id: str) -> BatchScrapeJobStatusResponse:
     def get(
         self, job_id: str, params: Optional[GetBatchScrapeJobParams] = None
     ) -> BatchScrapeJobResponse:
-        params_obj = params or GetBatchScrapeJobParams()
-        query_params = serialize_model_dump_to_dict(
-            params_obj,
+        query_params = serialize_model_dump_or_default(
+            params,
+            default_factory=GetBatchScrapeJobParams,
             error_message="Failed to serialize batch scrape get params",
         )
         response = self._client.transport.get(
diff --git a/hyperbrowser/client/managers/sync_manager/session.py b/hyperbrowser/client/managers/sync_manager/session.py
@@ -3,6 +3,7 @@
 import warnings
 from hyperbrowser.exceptions import HyperbrowserError
 from ..serialization_utils import (
+    serialize_model_dump_or_default,
     serialize_model_dump_to_dict,
     serialize_optional_model_dump_to_dict,
 )
@@ -38,9 +39,9 @@ def list(
         session_id: str,
         params: Optional[SessionEventLogListParams] = None,
     ) -> SessionEventLogListResponse:
-        params_obj = params or SessionEventLogListParams()
-        query_params = serialize_model_dump_to_dict(
-            params_obj,
+        query_params = serialize_model_dump_or_default(
+            params,
+            default_factory=SessionEventLogListParams,
             error_message="Failed to serialize session event log params",
         )
         response = self._client.transport.get(
@@ -77,9 +78,9 @@ def create(self, params: Optional[CreateSessionParams] = None) -> SessionDetail:
         )
 
     def get(self, id: str, params: Optional[SessionGetParams] = None) -> SessionDetail:
-        params_obj = params or SessionGetParams()
-        query_params = serialize_model_dump_to_dict(
-            params_obj,
+        query_params = serialize_model_dump_or_default(
+            params,
+            default_factory=SessionGetParams,
             error_message="Failed to serialize session get params",
         )
         response = self._client.transport.get(
@@ -103,9 +104,9 @@ def stop(self, id: str) -> BasicResponse:
         )
 
     def list(self, params: Optional[SessionListParams] = None) -> SessionListResponse:
-        params_obj = params or SessionListParams()
-        query_params = serialize_model_dump_to_dict(
-            params_obj,
+        query_params = serialize_model_dump_or_default(
+            params,
+            default_factory=SessionListParams,
             error_message="Failed to serialize session list params",
         )
         response = self._client.transport.get(
diff --git a/hyperbrowser/client/managers/web_payload_utils.py b/hyperbrowser/client/managers/web_payload_utils.py
@@ -10,7 +10,10 @@
 )
 
 from ..schema_utils import inject_web_output_schemas
-from .serialization_utils import serialize_model_dump_to_dict
+from .serialization_utils import (
+    serialize_model_dump_or_default,
+    serialize_model_dump_to_dict,
+)
 
 
 def build_web_fetch_payload(params: FetchParams) -> Dict[str, Any]:
@@ -50,18 +53,18 @@ def build_web_crawl_start_payload(params: StartWebCrawlJobParams) -> Dict[str, A
 def build_batch_fetch_get_params(
     params: Optional[GetBatchFetchJobParams] = None,
 ) -> Dict[str, Any]:
-    params_obj = params or GetBatchFetchJobParams()
-    return serialize_model_dump_to_dict(
-        params_obj,
+    return serialize_model_dump_or_default(
+        params,
+        default_factory=GetBatchFetchJobParams,
         error_message="Failed to serialize batch fetch get params",
     )
 
 
 def build_web_crawl_get_params(
     params: Optional[GetWebCrawlJobParams] = None,
 ) -> Dict[str, Any]:
-    params_obj = params or GetWebCrawlJobParams()
-    return serialize_model_dump_to_dict(
-        params_obj,
+    return serialize_model_dump_or_default(
+        params,
+        default_factory=GetWebCrawlJobParams,
         error_message="Failed to serialize web crawl get params",
     )
diff --git a/tests/test_architecture_marker_usage.py b/tests/test_architecture_marker_usage.py
@@ -16,6 +16,7 @@
     "tests/test_makefile_quality_targets.py",
     "tests/test_pyproject_architecture_marker.py",
     "tests/test_architecture_marker_usage.py",
+    "tests/test_default_serialization_helper_usage.py",
     "tests/test_plain_type_guard_usage.py",
     "tests/test_plain_type_identity_usage.py",
     "tests/test_plain_list_helper_usage.py",
diff --git a/tests/test_default_serialization_helper_usage.py b/tests/test_default_serialization_helper_usage.py
@@ -0,0 +1,25 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+MODULES = (
+    "hyperbrowser/client/managers/sync_manager/session.py",
+    "hyperbrowser/client/managers/async_manager/session.py",
+    "hyperbrowser/client/managers/sync_manager/profile.py",
+    "hyperbrowser/client/managers/async_manager/profile.py",
+    "hyperbrowser/client/managers/sync_manager/scrape.py",
+    "hyperbrowser/client/managers/async_manager/scrape.py",
+    "hyperbrowser/client/managers/sync_manager/crawl.py",
+    "hyperbrowser/client/managers/async_manager/crawl.py",
+    "hyperbrowser/client/managers/web_payload_utils.py",
+)
+
+
+def test_managers_use_default_serialization_helper_for_optional_query_params():
+    for module_path in MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        assert "serialize_model_dump_or_default(" in module_text
+        assert "params_obj = params or " not in module_text
diff --git a/tests/test_manager_serialization_utils.py b/tests/test_manager_serialization_utils.py
@@ -3,6 +3,7 @@
 import pytest
 
 from hyperbrowser.client.managers.serialization_utils import (
+    serialize_model_dump_or_default,
     serialize_model_dump_to_dict,
     serialize_optional_model_dump_to_dict,
 )
@@ -99,3 +100,40 @@ def test_serialize_optional_model_dump_to_dict_serializes_non_none_values():
 
     assert payload == {"value": 1}
     assert model.calls == [(False, False)]
+
+
+def test_serialize_model_dump_or_default_uses_default_factory_when_none():
+    model = _ModelWithPayload({"value": 2})
+
+    payload = serialize_model_dump_or_default(
+        None,
+        default_factory=lambda: model,
+        error_message="serialize failure",
+    )
+
+    assert payload == {"value": 2}
+    assert model.calls == [(True, True)]
+
+
+def test_serialize_model_dump_or_default_uses_provided_model_when_present():
+    default_model = _ModelWithPayload({"unused": True})
+    provided_model = _ModelWithPayload({"value": 3})
+    default_factory_called = False
+
+    def _default_factory():
+        nonlocal default_factory_called
+        default_factory_called = True
+        return default_model
+
+    payload = serialize_model_dump_or_default(
+        provided_model,
+        default_factory=_default_factory,
+        error_message="serialize failure",
+        exclude_none=False,
+        by_alias=False,
+    )
+
+    assert payload == {"value": 3}
+    assert provided_model.calls == [(False, False)]
+    assert default_model.calls == []
+    assert default_factory_called is False

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@`
`9`	`9`	`)`
`10`	`10`	`from hyperbrowser.models.session import BasicResponse`
`11`	`11`	`from ..serialization_utils import (`
`12`		`- serialize_model_dump_to_dict,`
	`12`	`+ serialize_model_dump_or_default,`
`13`	`13`	`serialize_optional_model_dump_to_dict,`
`14`	`14`	`)`
`15`	`15`	`from ..response_utils import parse_response_model`
`@@ -57,9 +57,9 @@ def delete(self, id: str) -> BasicResponse:`
`57`	`57`	`)`
`58`	`58`
`59`	`59`	`def list(self, params: Optional[ProfileListParams] = None) -> ProfileListResponse:`
`60`		`- params_obj = params or ProfileListParams()`
`61`		`- query_params = serialize_model_dump_to_dict(`
`62`		`- params_obj,`
	`60`	`+ query_params = serialize_model_dump_or_default(`
	`61`	`+ params,`
	`62`	`+ default_factory=ProfileListParams,`
`63`	`63`	`error_message="Failed to serialize profile list params",`
`64`	`64`	`)`
`65`	`65`	`response = self._client.transport.get(`