Fix Makefile python executable and format codebase

cursoragent · shrisukhani · cursoragent · commit 7c1d1f5bb2c8 · 2026-02-14T07:14:56.000Z
Co-authored-by: Shri Sukhani &lt;shrisukhani@users.noreply.github.com&gt;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -54,6 +54,12 @@ Or:
 make test
 ```
 
+### Architecture guard suites
+
+```bash
+make architecture-check
+```
+
 ### Full local CI parity
 
 ```bash
diff --git a/Makefile b/Makefile
@@ -1,26 +1,36 @@
-.PHONY: install lint format-check format compile test build check ci
+.PHONY: install lint format-check format compile test architecture-check build check ci
+
+PYTHON ?= python3
 
 install:
-	python -m pip install -e . pytest ruff build
+	$(PYTHON) -m pip install -e . pytest ruff build
 
 lint:
-	python -m ruff check .
+	$(PYTHON) -m ruff check .
 
 format-check:
-	python -m ruff format --check .
+	$(PYTHON) -m ruff format --check .
 
 format:
-	python -m ruff format .
+	$(PYTHON) -m ruff format .
 
 test:
-	python -m pytest -q
+	$(PYTHON) -m pytest -q
+
+architecture-check:
+	$(PYTHON) -m pytest -q \
+		tests/test_manager_model_dump_usage.py \
+		tests/test_mapping_reader_usage.py \
+		tests/test_mapping_keys_access_usage.py \
+		tests/test_tool_mapping_reader_usage.py \
+		tests/test_display_helper_usage.py
 
 compile:
-	python -m compileall -q hyperbrowser examples tests
+	$(PYTHON) -m compileall -q hyperbrowser examples tests
 
 build:
-	python -m build
+	$(PYTHON) -m build
 
-check: lint format-check compile test build
+check: lint format-check compile architecture-check test build
 
 ci: check
diff --git a/hyperbrowser/client/base.py b/hyperbrowser/client/base.py
@@ -210,8 +210,12 @@ def _build_url(self, path: str) -> str:
             normalized_path_only,
             normalized_path_query,
             _normalized_path_fragment,
-        ) = self._parse_url_components(normalized_path, component_label="normalized path")
-        normalized_query_suffix = f"?{normalized_path_query}" if normalized_path_query else ""
+        ) = self._parse_url_components(
+            normalized_path, component_label="normalized path"
+        )
+        normalized_query_suffix = (
+            f"?{normalized_path_query}" if normalized_path_query else ""
+        )
         decoded_path = ClientConfig._decode_url_component_with_limit(
             normalized_path_only, component_label="path"
         )
diff --git a/hyperbrowser/client/managers/response_utils.py b/hyperbrowser/client/managers/response_utils.py
@@ -1,6 +1,9 @@
 from typing import Any, Type, TypeVar
 
-from hyperbrowser.display_utils import format_string_key_for_error, normalize_display_text
+from hyperbrowser.display_utils import (
+    format_string_key_for_error,
+    normalize_display_text,
+)
 from hyperbrowser.exceptions import HyperbrowserError
 from hyperbrowser.mapping_utils import read_string_key_mapping
 
diff --git a/hyperbrowser/transport/base.py b/hyperbrowser/transport/base.py
@@ -1,7 +1,10 @@
 from abc import ABC, abstractmethod
 from typing import Generic, Mapping, Optional, Type, TypeVar, Union
 
-from hyperbrowser.display_utils import format_string_key_for_error, normalize_display_text
+from hyperbrowser.display_utils import (
+    format_string_key_for_error,
+    normalize_display_text,
+)
 from hyperbrowser.exceptions import HyperbrowserError
 from hyperbrowser.mapping_utils import read_string_key_mapping
 
diff --git a/tests/test_client_timeout.py b/tests/test_client_timeout.py
@@ -163,8 +163,7 @@ def _raise_isfinite_error(value: float) -> bool:
     assert exc_info.value.original_error is not None
 
 
-def test_sync_client_wraps_unexpected_timeout_float_conversion_failures(
-):
+def test_sync_client_wraps_unexpected_timeout_float_conversion_failures():
     class _BrokenDecimal(Decimal):
         def __float__(self) -> float:
             raise RuntimeError("unexpected float conversion failure")
@@ -178,8 +177,7 @@ def __float__(self) -> float:
     assert isinstance(exc_info.value.original_error, RuntimeError)
 
 
-def test_async_client_wraps_unexpected_timeout_float_conversion_failures(
-):
+def test_async_client_wraps_unexpected_timeout_float_conversion_failures():
     class _BrokenDecimal(Decimal):
         def __float__(self) -> float:
             raise RuntimeError("unexpected float conversion failure")
diff --git a/tests/test_display_utils.py b/tests/test_display_utils.py
@@ -1,4 +1,7 @@
-from hyperbrowser.display_utils import format_string_key_for_error, normalize_display_text
+from hyperbrowser.display_utils import (
+    format_string_key_for_error,
+    normalize_display_text,
+)
 
 
 def test_normalize_display_text_keeps_valid_input():
@@ -7,15 +10,12 @@ def test_normalize_display_text_keeps_valid_input():
 
 def test_normalize_display_text_replaces_control_characters_and_trims():
     assert (
-        normalize_display_text(" \nhello\tworld\r ", max_length=50)
-        == "?hello?world?"
+        normalize_display_text(" \nhello\tworld\r ", max_length=50) == "?hello?world?"
     )
 
 
 def test_normalize_display_text_truncates_long_values():
-    assert (
-        normalize_display_text("abcdefghij", max_length=7) == "... (truncated)"
-    )
+    assert normalize_display_text("abcdefghij", max_length=7) == "... (truncated)"
 
 
 def test_normalize_display_text_returns_empty_for_unreadable_inputs():
@@ -31,10 +31,7 @@ def test_normalize_display_text_returns_empty_for_non_string_inputs():
 
 
 def test_format_string_key_for_error_returns_normalized_key():
-    assert (
-        format_string_key_for_error(" \nkey\t ", max_length=20)
-        == "?key?"
-    )
+    assert format_string_key_for_error(" \nkey\t ", max_length=20) == "?key?"
 
 
 def test_format_string_key_for_error_returns_blank_fallback_for_empty_keys():
diff --git a/tests/test_manager_model_dump_usage.py b/tests/test_manager_model_dump_usage.py
@@ -2,7 +2,9 @@
 from pathlib import Path
 
 
-MANAGERS_DIR = Path(__file__).resolve().parents[1] / "hyperbrowser" / "client" / "managers"
+MANAGERS_DIR = (
+    Path(__file__).resolve().parents[1] / "hyperbrowser" / "client" / "managers"
+)
 
 
 def _manager_python_files() -> list[Path]:
diff --git a/tests/test_mapping_reader_usage.py b/tests/test_mapping_reader_usage.py
@@ -34,7 +34,10 @@ def _collect_mapping_reader_calls(module: ast.AST) -> list[int]:
     for node in ast.walk(module):
         if not isinstance(node, ast.Call):
             continue
-        if isinstance(node.func, ast.Name) and node.func.id == "read_string_key_mapping":
+        if (
+            isinstance(node.func, ast.Name)
+            and node.func.id == "read_string_key_mapping"
+        ):
             reader_calls.append(node.lineno)
     return reader_calls
 
diff --git a/tests/test_mapping_utils.py b/tests/test_mapping_utils.py
@@ -54,7 +54,9 @@ def _read_mapping(mapping_value):
         mapping_value,
         expected_mapping_error="expected mapping",
         read_keys_error="failed keys",
-        non_string_key_error_builder=lambda key: f"non-string key: {type(key).__name__}",
+        non_string_key_error_builder=lambda key: (
+            f"non-string key: {type(key).__name__}"
+        ),
         read_value_error_builder=lambda key_display: (
             f"failed value for '{key_display}'"
         ),
@@ -84,25 +86,23 @@ def test_read_string_key_mapping_rejects_non_string_keys():
 
 
 def test_read_string_key_mapping_wraps_value_read_failures():
-    with pytest.raises(
-        HyperbrowserError, match="failed value for 'field'"
-    ) as exc_info:
+    with pytest.raises(HyperbrowserError, match="failed value for 'field'") as exc_info:
         _read_mapping(_BrokenValueMapping())
 
     assert isinstance(exc_info.value.original_error, RuntimeError)
 
 
 def test_read_string_key_mapping_preserves_hyperbrowser_value_failures():
-    with pytest.raises(HyperbrowserError, match="custom value read failure") as exc_info:
+    with pytest.raises(
+        HyperbrowserError, match="custom value read failure"
+    ) as exc_info:
         _read_mapping(_HyperbrowserValueFailureMapping())
 
     assert exc_info.value.original_error is None
 
 
 def test_read_string_key_mapping_falls_back_for_unreadable_key_display():
-    with pytest.raises(
-        HyperbrowserError, match="failed value for '<unreadable key>'"
-    ):
+    with pytest.raises(HyperbrowserError, match="failed value for '<unreadable key>'"):
         read_string_key_mapping(
             _BrokenValueMapping(),
             expected_mapping_error="expected mapping",
@@ -180,9 +180,7 @@ def test_copy_mapping_values_by_string_keys_returns_selected_values():
 
 
 def test_copy_mapping_values_by_string_keys_wraps_value_read_failures():
-    with pytest.raises(
-        HyperbrowserError, match="failed value for 'field'"
-    ) as exc_info:
+    with pytest.raises(HyperbrowserError, match="failed value for 'field'") as exc_info:
         copy_mapping_values_by_string_keys(
             _BrokenValueMapping(),
             ["field"],
@@ -196,7 +194,9 @@ def test_copy_mapping_values_by_string_keys_wraps_value_read_failures():
 
 
 def test_copy_mapping_values_by_string_keys_preserves_hyperbrowser_failures():
-    with pytest.raises(HyperbrowserError, match="custom value read failure") as exc_info:
+    with pytest.raises(
+        HyperbrowserError, match="custom value read failure"
+    ) as exc_info:
         copy_mapping_values_by_string_keys(
             _HyperbrowserValueFailureMapping(),
             ["field"],
@@ -210,9 +210,7 @@ def test_copy_mapping_values_by_string_keys_preserves_hyperbrowser_failures():
 
 
 def test_copy_mapping_values_by_string_keys_falls_back_for_unreadable_key_display():
-    with pytest.raises(
-        HyperbrowserError, match="failed value for '<unreadable key>'"
-    ):
+    with pytest.raises(HyperbrowserError, match="failed value for '<unreadable key>'"):
         copy_mapping_values_by_string_keys(
             _BrokenValueMapping(),
             ["field"],
diff --git a/tests/test_transport_error_utils.py b/tests/test_transport_error_utils.py
@@ -1098,7 +1098,9 @@ def test_extract_error_message_handles_truncate_sanitization_runtime_failures(
     def _raise_sanitize_error(_message: str) -> str:
         raise RuntimeError("sanitize exploded")
 
-    monkeypatch.setattr(error_utils, "_sanitize_error_message_text", _raise_sanitize_error)
+    monkeypatch.setattr(
+        error_utils, "_sanitize_error_message_text", _raise_sanitize_error
+    )
 
     message = extract_error_message(
         _DummyResponse("   ", text="   "),
diff --git a/tests/test_url_building.py b/tests/test_url_building.py
@@ -356,6 +356,7 @@ def test_client_build_url_rejects_empty_or_non_string_paths():
 def test_client_build_url_rejects_string_subclass_path_inputs():
     client = Hyperbrowser(config=ClientConfig(api_key="test-key"))
     try:
+
         class _BrokenPath(str):
             pass
 
@@ -412,6 +413,7 @@ def test_client_build_url_wraps_path_parse_runtime_errors(
 ):
     client = Hyperbrowser(config=ClientConfig(api_key="test-key"))
     try:
+
         def _raise_parse_runtime_error(_value: str):
             raise RuntimeError("path parse exploded")
 
@@ -430,6 +432,7 @@ def test_client_build_url_preserves_hyperbrowser_path_parse_errors(
 ):
     client = Hyperbrowser(config=ClientConfig(api_key="test-key"))
     try:
+
         def _raise_parse_hyperbrowser_error(_value: str):
             raise HyperbrowserError("custom path parse failure")
 
@@ -454,12 +457,15 @@ def test_client_build_url_wraps_path_component_access_runtime_errors(
 ):
     client = Hyperbrowser(config=ClientConfig(api_key="test-key"))
     try:
+
         class _BrokenParsedPath:
             @property
             def scheme(self) -> str:
                 raise RuntimeError("path scheme exploded")
 
-        monkeypatch.setattr(client_base_module, "urlparse", lambda _value: _BrokenParsedPath())
+        monkeypatch.setattr(
+            client_base_module, "urlparse", lambda _value: _BrokenParsedPath()
+        )
 
         with pytest.raises(
             HyperbrowserError, match="Failed to parse path components"
@@ -476,14 +482,17 @@ def test_client_build_url_rejects_invalid_path_parser_component_types(
 ):
     client = Hyperbrowser(config=ClientConfig(api_key="test-key"))
     try:
+
         class _InvalidParsedPath:
             scheme = object()
             netloc = ""
             path = "/session"
             query = ""
             fragment = ""
 
-        monkeypatch.setattr(client_base_module, "urlparse", lambda _value: _InvalidParsedPath())
+        monkeypatch.setattr(
+            client_base_module, "urlparse", lambda _value: _InvalidParsedPath()
+        )
 
         with pytest.raises(
             HyperbrowserError, match="path parser returned invalid URL components"
@@ -531,7 +540,9 @@ def _conditional_urlparse(value: str):
 
         monkeypatch.setattr(client_base_module, "urlparse", _conditional_urlparse)
 
-        with pytest.raises(HyperbrowserError, match="Failed to parse base_url") as exc_info:
+        with pytest.raises(
+            HyperbrowserError, match="Failed to parse base_url"
+        ) as exc_info:
             client._build_url("/session")
 
         assert isinstance(exc_info.value.original_error, RuntimeError)
diff --git a/tests/test_web_manager_serialization.py b/tests/test_web_manager_serialization.py
@@ -37,7 +37,9 @@ def __init__(self) -> None:
     def post(self, url: str, data=None) -> SimpleNamespace:
         self.post_calls.append((url, data))
         if url == "/web/fetch":
-            return SimpleNamespace(data={"jobId": "job_sync_fetch", "status": "completed"})
+            return SimpleNamespace(
+                data={"jobId": "job_sync_fetch", "status": "completed"}
+            )
         if url == "/web/search":
             return SimpleNamespace(
                 data={
