Centralize plain-type helper utilities

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

Author: cursoragent

hyperbrowser/client/managers/async_manager/computer_action.py

@@ -1,6 +1,7 @@
 from pydantic import BaseModel
 from typing import Union, List, Optional
 from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.type_utils import is_string_subclass_instance
 from ..response_utils import parse_response_model
 from ..serialization_utils import serialize_model_dump_to_dict
 from hyperbrowser.models import (
@@ -33,7 +34,7 @@ async def _execute_request(
     ) -> ComputerActionResponse:
         if type(session) is str:
             session = await self._client.sessions.get(session)
-        elif type(session) is not str and str in type(session).__mro__:
+        elif is_string_subclass_instance(session):
             raise HyperbrowserError(
                 "session must be a plain string session ID or SessionDetail"
             )

hyperbrowser/client/managers/async_manager/session.py

@@ -3,6 +3,7 @@
 from typing import IO, List, Optional, Union, overload
 import warnings
 from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.type_utils import is_string_subclass_instance
 from ...file_utils import ensure_existing_file_path
 from ..serialization_utils import serialize_model_dump_to_dict
 from ..session_utils import (
@@ -192,7 +193,7 @@ async def upload_file(
                     f"Failed to open upload file at path: {file_path}",
                     original_error=exc,
                 ) from exc
-        elif type(file_input) is not str and str in type(file_input).__mro__:
+        elif is_string_subclass_instance(file_input):
             raise HyperbrowserError("file_input path must be a plain string path")
         else:
             try:

hyperbrowser/client/managers/sync_manager/computer_action.py

@@ -1,6 +1,7 @@
 from pydantic import BaseModel
 from typing import Union, List, Optional
 from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.type_utils import is_string_subclass_instance
 from ..response_utils import parse_response_model
 from ..serialization_utils import serialize_model_dump_to_dict
 from hyperbrowser.models import (
@@ -33,7 +34,7 @@ def _execute_request(
     ) -> ComputerActionResponse:
         if type(session) is str:
             session = self._client.sessions.get(session)
-        elif type(session) is not str and str in type(session).__mro__:
+        elif is_string_subclass_instance(session):
             raise HyperbrowserError(
                 "session must be a plain string session ID or SessionDetail"
             )

hyperbrowser/client/managers/sync_manager/session.py

@@ -3,6 +3,7 @@
 from typing import IO, List, Optional, Union, overload
 import warnings
 from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.type_utils import is_string_subclass_instance
 from ...file_utils import ensure_existing_file_path
 from ..serialization_utils import serialize_model_dump_to_dict
 from ..session_utils import (
@@ -184,7 +185,7 @@ def upload_file(
                     f"Failed to open upload file at path: {file_path}",
                     original_error=exc,
                 ) from exc
-        elif type(file_input) is not str and str in type(file_input).__mro__:
+        elif is_string_subclass_instance(file_input):
             raise HyperbrowserError("file_input path must be a plain string path")
         else:
             try:

hyperbrowser/models/session.py

@@ -14,6 +14,12 @@
     SessionRegion,
     SessionEventLogType,
 )
+from hyperbrowser.type_utils import (
+    is_int_subclass_instance,
+    is_plain_int,
+    is_plain_string,
+    is_string_subclass_instance,
+)
 
 SessionStatus = Literal["active", "closed", "error"]
 
@@ -149,20 +155,20 @@ def parse_timestamp(cls, value: Optional[Union[str, int]]) -> Optional[int]:
             raise ValueError(
                 "timestamp values must be integers or plain numeric strings"
             )
-        if value_type is int:
+        if is_plain_int(value):
             return value
-        if int in value_type.__mro__:
+        if is_int_subclass_instance(value):
             raise ValueError(
                 "timestamp values must be plain integers or plain numeric strings"
             )
-        if value_type is str:
+        if is_plain_string(value):
             try:
                 return int(value)
             except Exception as exc:
                 raise ValueError(
                     "timestamp string values must be integer-formatted"
                 ) from exc
-        if str in value_type.__mro__:
+        if is_string_subclass_instance(value):
             raise ValueError("timestamp string values must be plain strings")
         raise ValueError(
             "timestamp values must be plain integers or plain numeric strings"

hyperbrowser/tools/__init__.py

@@ -9,6 +9,7 @@
     copy_mapping_values_by_string_keys,
     read_string_mapping_keys,
 )
+from hyperbrowser.type_utils import is_string_subclass_instance
 from hyperbrowser.models.agents.browser_use import StartBrowserUseTaskParams
 from hyperbrowser.models.crawl import StartCrawlJobParams
 from hyperbrowser.models.extract import StartExtractJobParams
@@ -207,7 +208,7 @@ def _normalize_optional_text_field_value(
                 error_message,
                 original_error=exc,
             ) from exc
-    if type(field_value) is not str and str in type(field_value).__mro__:
+    if is_string_subclass_instance(field_value):
         raise HyperbrowserError(error_message)
     if isinstance(field_value, (bytes, bytearray, memoryview)):
         try:

hyperbrowser/transport/error_utils.py

@@ -5,6 +5,10 @@
 from typing import Any
 
 import httpx
+from hyperbrowser.type_utils import (
+    is_plain_string as _is_plain_string,
+    is_string_subclass_instance as _is_string_subclass_instance,
+)
 
 _HTTP_METHOD_TOKEN_PATTERN = re.compile(r"^[!#$%&'*+\-.^_`|~0-9A-Z]+$")
 _NUMERIC_LIKE_URL_PATTERN = re.compile(
@@ -45,16 +49,6 @@
     "-infinity",
 }
 
-
-def _is_plain_string(value: Any) -> bool:
-    return type(value) is str
-
-
-def _is_string_subclass_instance(value: Any) -> bool:
-    value_type = type(value)
-    return value_type is not str and str in value_type.__mro__
-
-
 def _safe_to_string(value: Any) -> str:
     try:
         normalized_value = str(value)

hyperbrowser/type_utils.py

@@ -0,0 +1,26 @@
+from typing import Any, Type
+
+
+def is_plain_instance(value: Any, expected_type: Type[object]) -> bool:
+    return type(value) is expected_type
+
+
+def is_subclass_instance(value: Any, expected_type: Type[object]) -> bool:
+    value_type = type(value)
+    return value_type is not expected_type and expected_type in value_type.__mro__
+
+
+def is_plain_string(value: Any) -> bool:
+    return is_plain_instance(value, str)
+
+
+def is_string_subclass_instance(value: Any) -> bool:
+    return is_subclass_instance(value, str)
+
+
+def is_plain_int(value: Any) -> bool:
+    return is_plain_instance(value, int)
+
+
+def is_int_subclass_instance(value: Any) -> bool:
+    return is_subclass_instance(value, int)

tests/test_type_utils.py

@@ -0,0 +1,45 @@
+from hyperbrowser.type_utils import (
+    is_int_subclass_instance,
+    is_plain_instance,
+    is_plain_int,
+    is_plain_string,
+    is_string_subclass_instance,
+    is_subclass_instance,
+)
+
+
+def test_is_plain_instance_requires_concrete_type_match():
+    assert is_plain_instance("value", str) is True
+    assert is_plain_instance(10, int) is True
+    assert is_plain_instance(True, int) is False
+    assert is_plain_instance("value", int) is False
+
+
+def test_is_subclass_instance_detects_string_subclasses_only():
+    class _StringSubclass(str):
+        pass
+
+    assert is_subclass_instance(_StringSubclass("value"), str) is True
+    assert is_subclass_instance("value", str) is False
+    assert is_subclass_instance(10, str) is False
+
+
+def test_string_helpers_enforce_plain_string_boundaries():
+    class _StringSubclass(str):
+        pass
+
+    assert is_plain_string("value") is True
+    assert is_plain_string(_StringSubclass("value")) is False
+    assert is_string_subclass_instance("value") is False
+    assert is_string_subclass_instance(_StringSubclass("value")) is True
+
+
+def test_int_helpers_enforce_plain_integer_boundaries():
+    class _IntSubclass(int):
+        pass
+
+    assert is_plain_int(10) is True
+    assert is_plain_int(_IntSubclass(10)) is False
+    assert is_int_subclass_instance(10) is False
+    assert is_int_subclass_instance(_IntSubclass(10)) is True
+    assert is_int_subclass_instance(True) is True