Refactor key formatting through shared helper

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

Author: cursoragent

hyperbrowser/client/managers/response_utils.py

@@ -1,6 +1,6 @@
 from typing import Any, Type, TypeVar
 
-from hyperbrowser.display_utils import 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
 
@@ -20,13 +20,7 @@ def _normalize_operation_name_for_error(operation_name: str) -> str:
 
 
 def _normalize_response_key_for_error(key: str) -> str:
-    normalized_key = normalize_display_text(
-        key,
-        max_length=_MAX_KEY_DISPLAY_LENGTH,
-    )
-    if not normalized_key:
-        return "<blank key>"
-    return normalized_key
+    return format_string_key_for_error(key, max_length=_MAX_KEY_DISPLAY_LENGTH)
 
 
 def parse_response_model(

hyperbrowser/client/managers/session_utils.py

@@ -1,6 +1,6 @@
 from typing import Any, List, Type, TypeVar
 
-from hyperbrowser.display_utils import normalize_display_text
+from hyperbrowser.display_utils import format_string_key_for_error
 from hyperbrowser.exceptions import HyperbrowserError
 from hyperbrowser.models.session import SessionRecording
 from .list_parsing_utils import parse_mapping_list_items
@@ -11,13 +11,7 @@
 
 
 def _format_recording_key_display(key: str) -> str:
-    normalized_key = normalize_display_text(
-        key,
-        max_length=_MAX_KEY_DISPLAY_LENGTH,
-    )
-    if not normalized_key:
-        return "<blank key>"
-    return normalized_key
+    return format_string_key_for_error(key, max_length=_MAX_KEY_DISPLAY_LENGTH)
 
 
 def parse_session_response_model(

hyperbrowser/display_utils.py

@@ -19,3 +19,15 @@ def normalize_display_text(value: str, *, max_length: int) -> str:
         return f"{sanitized_value[:available_length]}{_TRUNCATED_DISPLAY_SUFFIX}"
     except Exception:
         return ""
+
+
+def format_string_key_for_error(
+    key: str,
+    *,
+    max_length: int,
+    blank_fallback: str = "<blank key>",
+) -> str:
+    normalized_key = normalize_display_text(key, max_length=max_length)
+    if not normalized_key:
+        return blank_fallback
+    return normalized_key

hyperbrowser/tools/__init__.py

@@ -3,7 +3,7 @@
 from collections.abc import Mapping as MappingABC
 from typing import Any, Dict, Mapping
 
-from hyperbrowser.display_utils import normalize_display_text
+from hyperbrowser.display_utils import format_string_key_for_error
 from hyperbrowser.exceptions import HyperbrowserError
 from hyperbrowser.mapping_utils import copy_mapping_values_by_string_keys
 from hyperbrowser.models.agents.browser_use import StartBrowserUseTaskParams
@@ -54,13 +54,7 @@ def _has_declared_attribute(
 
 
 def _format_tool_param_key_for_error(key: str) -> str:
-    normalized_key = normalize_display_text(
-        key,
-        max_length=_MAX_KEY_DISPLAY_LENGTH,
-    )
-    if not normalized_key:
-        return "<blank key>"
-    return normalized_key
+    return format_string_key_for_error(key, max_length=_MAX_KEY_DISPLAY_LENGTH)
 
 
 def _normalize_extract_schema_mapping(

hyperbrowser/transport/base.py

@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
 from typing import Generic, Mapping, Optional, Type, TypeVar, Union
 
-from hyperbrowser.display_utils import 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
 
@@ -31,16 +31,10 @@ def _safe_model_name(model: object) -> str:
 
 
 def _format_mapping_key_for_error(key: str) -> str:
-    normalized_key = normalize_display_text(
-        key, max_length=_MAX_MAPPING_KEY_DISPLAY_LENGTH
+    return format_string_key_for_error(
+        key,
+        max_length=_MAX_MAPPING_KEY_DISPLAY_LENGTH,
     )
-    if normalized_key:
-        return normalized_key
-    try:
-        _ = "".join(character for character in key)
-    except Exception:
-        return "<unreadable key>"
-    return "<blank key>"
 
 
 def _normalize_transport_api_key(api_key: str) -> str:

tests/test_display_utils.py

@@ -1,4 +1,4 @@
-from hyperbrowser.display_utils import normalize_display_text
+from hyperbrowser.display_utils import format_string_key_for_error, normalize_display_text
 
 
 def test_normalize_display_text_keeps_valid_input():
@@ -28,3 +28,21 @@ def __iter__(self):  # type: ignore[override]
 
 def test_normalize_display_text_returns_empty_for_non_string_inputs():
     assert normalize_display_text(123, max_length=20) == ""  # type: ignore[arg-type]
+
+
+def test_format_string_key_for_error_returns_normalized_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():
+    assert format_string_key_for_error("   ", max_length=20) == "<blank key>"
+
+
+def test_format_string_key_for_error_supports_custom_blank_fallback():
+    assert (
+        format_string_key_for_error("   ", max_length=20, blank_fallback="<empty>")
+        == "<empty>"
+    )