hud-python 0.4.20__py3-none-any.whl → 0.4.22__py3-none-any.whl

hud/shared/tests/test_exceptions.py

@@ -1,179 +1,420 @@
-"""Tests for server exceptions."""
+"""Tests for the HUD SDK Exception System.
+
+This module tests the intelligent exception handling with automatic error
+classification and helpful hints for users.
+"""
 
 from __future__ import annotations
 
-from unittest.mock import MagicMock
+import json
+from unittest.mock import Mock, patch
 
 import httpx
+import pytest
 
 from hud.shared.exceptions import (
-    GymMakeException,
     HudAuthenticationError,
+    HudClientError,
+    HudConfigError,
     HudException,
-    HudNetworkError,
+    HudRateLimitError,
     HudRequestError,
     HudTimeoutError,
+    HudToolNotFoundError,
+)
+from hud.shared.hints import (
+    CLIENT_NOT_INITIALIZED,
+    HUD_API_KEY_MISSING,
+    INVALID_CONFIG,
+    RATE_LIMIT_HIT,
+    TOOL_NOT_FOUND,
 )
 
 
-class TestHudRequestError:
-    """Test HudRequestError exception."""
-
-    def test_from_httpx_error_with_json_detail(self):
-        """Test creating from httpx error with JSON detail."""
-        response = MagicMock()
-        response.status_code = 400
-        response.json.return_value = {"detail": "Bad request details"}
-
-        error = httpx.HTTPStatusError("Test", request=MagicMock(), response=response)
-
-        hud_error = HudRequestError.from_httpx_error(error, context="Test context")
-
-        assert hud_error.status_code == 400
-        assert "Test context" in str(hud_error)
-        assert "Bad request details" in str(hud_error)
-
-    def test_from_httpx_error_with_small_json_no_detail(self):
-        """Test creating from httpx error with small JSON but no detail field."""
-        response = MagicMock()
-        response.status_code = 400
-        response.json.return_value = {"error": "test", "code": 123}
-
-        error = httpx.HTTPStatusError("Test", request=MagicMock(), response=response)
-
-        hud_error = HudRequestError.from_httpx_error(error)
-
-        assert hud_error.status_code == 400
-        assert "JSON response:" in str(hud_error)
-        # Check for the dictionary representation (not exact JSON string)
-        assert "'error': 'test'" in str(hud_error)
-        assert "'code': 123" in str(hud_error)
-
-    def test_from_httpx_error_json_parse_failure(self):
-        """Test creating from httpx error when JSON parsing fails."""
-        response = MagicMock()
-        response.status_code = 500
-        response.json.side_effect = ValueError("Invalid JSON")
-
-        error = httpx.HTTPStatusError("Test", request=MagicMock(), response=response)
-
-        hud_error = HudRequestError.from_httpx_error(error)
-
-        assert hud_error.status_code == 500
-        assert "Request failed with status 500" in str(hud_error)
-
-    def test_from_httpx_error_large_json_response(self):
-        """Test creating from httpx error with large JSON response."""
-        response = MagicMock()
-        response.status_code = 400
-        # Large JSON object (more than 5 keys)
-        response.json.return_value = {
-            "field1": "value1",
-            "field2": "value2",
-            "field3": "value3",
-            "field4": "value4",
-            "field5": "value5",
-            "field6": "value6",
-        }
-
-        error = httpx.HTTPStatusError("Test", request=MagicMock(), response=response)
-
-        hud_error = HudRequestError.from_httpx_error(error)
-
-        assert hud_error.status_code == 400
-        # Should not include JSON in message since it's large
-        assert "JSON response:" not in str(hud_error)
-        assert "Request failed with status 400" in str(hud_error)
-
-    def test_str_method(self):
-        """Test string representation of HudRequestError."""
-        error = HudRequestError("Test error message", 404, '{"extra": "data"}')
-
-        error_str = str(error)
-        assert "Test error message" in error_str
-        assert "404" in error_str
-        assert "extra" in error_str
-
-
-class TestHudNetworkError:
-    """Test HudNetworkError exception."""
-
-    def test_initialization_and_str(self):
-        """Test HudNetworkError initialization and string representation."""
-        error = HudNetworkError("Network failure: Connection refused")
+class TestHudExceptionAutoConversion:
+    """Test automatic exception conversion via 'raise HudException() from e'."""
+
+    def test_client_not_initialized_error(self):
+        """Test that 'not initialized' errors become HudClientError."""
+        try:
+            raise ValueError("Client not initialized - call initialize() first")
+        except Exception as e:
+            with pytest.raises(HudClientError) as exc_info:
+                raise HudException from e
+
+            assert exc_info.value.hints == [CLIENT_NOT_INITIALIZED]
+            assert str(exc_info.value) == "Client not initialized - call initialize() first"
+
+    def test_not_connected_error(self):
+        """Test that 'not connected' errors become HudClientError."""
+        try:
+            raise RuntimeError("Session not connected to server")
+        except Exception as e:
+            with pytest.raises(HudClientError) as exc_info:
+                raise HudException from e
+
+            assert exc_info.value.hints == [CLIENT_NOT_INITIALIZED]
+
+    def test_config_invalid_json_error(self):
+        """Test that JSON errors become HudConfigError."""
+        try:
+            json.loads("{invalid json}")
+        except json.JSONDecodeError as e:
+            with pytest.raises(HudConfigError) as exc_info:
+                raise HudException from e
+
+            assert exc_info.value.hints == [INVALID_CONFIG]
+
+    def test_config_error_keyword(self):
+        """Test that errors with 'config' become HudConfigError."""
+        try:
+            raise ValueError("Invalid config: missing required field 'url'")
+        except Exception as e:
+            with pytest.raises(HudConfigError) as exc_info:
+                raise HudException from e
+
+            assert exc_info.value.hints == [INVALID_CONFIG]
+
+    def test_tool_not_found_error(self):
+        """Test that tool not found errors become HudToolNotFoundError."""
+        try:
+            raise KeyError("Tool 'missing_tool' not found in registry")
+        except Exception as e:
+            with pytest.raises(HudToolNotFoundError) as exc_info:
+                raise HudException from e
+
+            assert exc_info.value.hints == [TOOL_NOT_FOUND]
+
+    def test_tool_not_exist_error(self):
+        """Test that tool not exist errors become HudToolNotFoundError."""
+        try:
+            raise RuntimeError("Tool does not exist: calculator")
+        except Exception as e:
+            with pytest.raises(HudToolNotFoundError) as exc_info:
+                raise HudException from e
+
+            assert exc_info.value.hints == [TOOL_NOT_FOUND]
+
+    def test_hud_api_key_error(self):
+        """Test that HUD API key errors become HudAuthenticationError."""
+        try:
+            raise ValueError("API key missing for mcp.hud.so")
+        except Exception as e:
+            with pytest.raises(HudAuthenticationError) as exc_info:
+                raise HudException from e
+
+            assert exc_info.value.hints == [HUD_API_KEY_MISSING]
+
+    def test_hud_authorization_error(self):
+        """Test that HUD authorization errors become HudAuthenticationError."""
+        try:
+            raise PermissionError("Authorization failed for HUD API")
+        except Exception as e:
+            with pytest.raises(HudAuthenticationError) as exc_info:
+                raise HudException from e
+
+            assert exc_info.value.hints == [HUD_API_KEY_MISSING]
+
+    def test_rate_limit_error(self):
+        """Test that rate limit errors become HudRateLimitError."""
+        try:
+            raise RuntimeError("Rate limit exceeded")
+        except Exception as e:
+            with pytest.raises(HudRateLimitError) as exc_info:
+                raise HudException from e
+
+            assert exc_info.value.hints == [RATE_LIMIT_HIT]
+
+    def test_too_many_requests_error(self):
+        """Test that 'too many request' errors become HudRateLimitError."""
+        try:
+            raise httpx.HTTPStatusError("Too many requests", request=Mock(), response=Mock())
+        except Exception as e:
+            with pytest.raises(HudRateLimitError) as exc_info:
+                raise HudException from e
+
+            assert exc_info.value.hints == [RATE_LIMIT_HIT]
+
+    def test_timeout_error(self):
+        """Test that TimeoutError becomes HudTimeoutError."""
+        try:
+            raise TimeoutError("Operation timed out")
+        except Exception as e:
+            with pytest.raises(HudTimeoutError) as exc_info:
+                raise HudException from e
+
+            assert exc_info.value.hints == []  # No default hints for timeout
+
+    def test_asyncio_timeout_error(self):
+        """Test that asyncio.TimeoutError becomes HudTimeoutError."""
+        try:
+            raise TimeoutError("Async operation timed out")
+        except Exception as e:
+            with pytest.raises(HudTimeoutError) as exc_info:
+                raise HudException from e
+
+            assert str(exc_info.value) == "Async operation timed out"
+
+    def test_generic_error_remains_hudexception(self):
+        """Test that unmatched errors remain as base HudException."""
+        try:
+            raise ValueError("Some random error")
+        except Exception as e:
+            with pytest.raises(HudException) as exc_info:
+                raise HudException from e
+
+            # Should be base HudException, not a subclass
+            assert type(exc_info.value) is HudException
+            assert exc_info.value.hints == []
+
+    def test_custom_message_override(self):
+        """Test that custom message overrides the original."""
+        try:
+            raise ValueError("Original error")
+        except Exception as e:
+            with pytest.raises(HudException) as exc_info:
+                raise HudException("Custom error message") from e
+
+            assert str(exc_info.value) == "Custom error message"
+
+    def test_already_hud_exception_passthrough(self):
+        """Test that existing HudExceptions are not re-wrapped."""
+        original = HudAuthenticationError("Already a HUD exception")
+
+        try:
+            raise original
+        except Exception as e:
+            with pytest.raises(HudAuthenticationError) as exc_info:
+                raise HudException from e
+
+            # Should be the same instance
+            assert exc_info.value is original
 
-        error_str = str(error)
-        assert "Network failure" in error_str
-        assert "Connection refused" in error_str
 
+class TestHudRequestError:
+    """Test HudRequestError specific behavior."""
+
+    def test_401_adds_auth_hint(self):
+        """Test that 401 status adds authentication hint."""
+        error = HudRequestError("Unauthorized", status_code=401)
+        assert HUD_API_KEY_MISSING in error.hints
+
+    def test_403_adds_auth_hint(self):
+        """Test that 403 status adds authentication hint."""
+        error = HudRequestError("Forbidden", status_code=403)
+        assert HUD_API_KEY_MISSING in error.hints
+
+    def test_429_adds_rate_limit_hint(self):
+        """Test that 429 status adds rate limit hint."""
+        error = HudRequestError("Too Many Requests", status_code=429)
+        assert RATE_LIMIT_HIT in error.hints
+
+    def test_other_status_no_default_hints(self):
+        """Test that other status codes don't add default hints."""
+        error = HudRequestError("Server Error", status_code=500)
+        assert error.hints == []
+
+    def test_explicit_hints_override_defaults(self):
+        """Test that explicit hints override status-based defaults."""
+        from hud.shared.hints import Hint
+
+        custom_hint = Hint(title="Custom Error", message="This is a custom hint")
+        error = HudRequestError("Unauthorized", status_code=401, hints=[custom_hint])
+        assert error.hints == [custom_hint]
+        assert HUD_API_KEY_MISSING not in error.hints
+
+    def test_from_httpx_error(self):
+        """Test creating from HTTPx error."""
+        request = httpx.Request("GET", "https://api.test.com")
+        response = httpx.Response(404, json={"detail": "Not found"}, request=request)
+        httpx_error = httpx.HTTPStatusError("Not found", request=request, response=response)
+
+        error = HudRequestError.from_httpx_error(httpx_error, context="Testing")
+
+        assert error.status_code == 404
+        assert "Testing" in str(error)
+        assert "Not found" in str(error)
+        assert error.response_json == {"detail": "Not found"}
+
+
+class TestMCPErrorHandling:
+    """Test handling of MCP-specific errors."""
+
+    @pytest.mark.asyncio
+    async def test_mcp_error_handling(self):
+        """Test that McpError is handled appropriately."""
+        # Since McpError is imported dynamically, we'll mock it
+        with patch("hud.clients.mcp_use.McpError") as MockMcpError:
+            MockMcpError.side_effect = Exception
+
+            # Create a mock MCP error
+            mcp_error = Exception("MCP protocol error: Unknown method")
+            mcp_error.__class__.__name__ = "McpError"
+
+            try:
+                raise mcp_error
+            except Exception as e:
+                # This would typically be caught in the client code
+                # and re-raised as HudException
+                with pytest.raises(HudException) as exc_info:
+                    raise HudException from e
+
+                assert "MCP protocol error" in str(exc_info.value)
+
+    def test_mcp_tool_error_result(self):
+        """Test handling of MCP tool execution errors (isError: true)."""
+        # Simulate an MCP tool result with error
+        tool_result = {
+            "content": [{"type": "text", "text": "Failed to fetch data: API rate limit exceeded"}],
+            "isError": True,
+        }
 
-class TestHudTimeoutError:
-    """Test HudTimeoutError exception."""
+        # In real usage, this would be checked in the client
+        if tool_result.get("isError"):
+            error_text = tool_result["content"][0]["text"]
 
-    def test_initialization(self):
-        """Test HudTimeoutError initialization."""
-        error = HudTimeoutError("Request timed out after 30.0 seconds")
+            try:
+                raise RuntimeError(error_text)
+            except Exception as e:
+                with pytest.raises(HudRateLimitError) as exc_info:
+                    raise HudException from e
 
-        error_str = str(error)
-        assert "Request timed out" in error_str
-        assert "30.0" in error_str
+                assert exc_info.value.hints == [RATE_LIMIT_HIT]
 
-    def test_str_method(self):
-        """Test string representation of HudTimeoutError."""
-        error = HudTimeoutError("Timeout occurred after 60.0 seconds")
 
-        error_str = str(error)
-        assert "Timeout occurred" in error_str
-        assert "60.0" in error_str
+class TestExceptionIntegration:
+    """Test exception handling in integrated scenarios."""
 
+    @pytest.mark.asyncio
+    async def test_client_initialization_flow(self):
+        """Test exception flow during client initialization."""
+        from hud.clients.base import BaseHUDClient
 
-class TestHudAuthenticationError:
-    """Test HudAuthenticationError exception."""
+        # Mock a client that fails initialization
+        client = Mock(spec=BaseHUDClient)
 
-    def test_inheritance(self):
-        """Test that HudAuthenticationError inherits from HudException."""
-        error = HudAuthenticationError("Auth failed")
-
-        assert isinstance(error, HudException)
-        error_str = str(error)
-        assert "Auth failed" in error_str
+        # Simulate missing config
+        try:
+            if not hasattr(client, "_mcp_config"):
+                raise ValueError("MCP config not set")
+        except Exception as e:
+            with pytest.raises(HudConfigError) as exc_info:
+                raise HudException from e
 
+            assert exc_info.value.hints == [INVALID_CONFIG]
 
-class TestGymMakeException:
-    """Test GymMakeException."""
+    def test_json_parsing_flow(self):
+        """Test exception flow during JSON parsing."""
+        invalid_json = '{"incomplete": '
 
-    def test_initialization_and_str(self):
-        """Test GymMakeException initialization and string representation."""
-        data = {"env_id": "test-env", "error": "invalid config"}
-        error = GymMakeException("Failed to create environment", data)
+        try:
+            _ = json.loads(invalid_json)
+        except json.JSONDecodeError as e:
+            with pytest.raises(HudConfigError) as exc_info:
+                raise HudException from e
 
-        assert error.data == data
+            assert "Expecting value" in str(exc_info.value)
+            assert exc_info.value.hints == [INVALID_CONFIG]
 
-        error_str = str(error)
-        assert "Failed to create environment" in error_str
-        assert "Data:" in error_str
-        assert "env_id" in error_str
-        assert "test-env" in error_str
-        assert "invalid config" in error_str
+    @pytest.mark.asyncio
+    async def test_network_error_flow(self):
+        """Test exception flow during network operations."""
+        # Simulate a connection error
+        try:
+            raise ConnectionError("Connection refused")
+        except Exception as e:
+            with pytest.raises(HudException) as exc_info:
+                raise HudException("Failed to connect to server") from e
 
+            # Should remain base HudException for generic connection errors
+            assert type(exc_info.value) is HudException
+            assert str(exc_info.value) == "Failed to connect to server"
 
-class TestHudException:
-    """Test base HudException class."""
 
-    def test_str_with_response_json(self):
-        """Test HudException string representation with response_json."""
-        response_data = {"error": "test error", "code": 42}
-        error = HudException("Base error message", response_data)
-
-        error_str = str(error)
-        assert "Base error message" in error_str
-        assert "error" in error_str
-        assert "test error" in error_str
+class TestExceptionRendering:
+    """Test how exceptions are rendered and displayed."""
 
-    def test_str_without_response_json(self):
-        """Test HudException string representation without response_json."""
-        error = HudException("Just a message")
+    def test_exception_string_representation(self):
+        """Test __str__ method of exceptions."""
+        error = HudRequestError(
+            "Request failed", status_code=404, response_json={"error": "Not found"}
+        )
 
         error_str = str(error)
-        assert error_str == "Just a message"
-        assert "Response:" not in error_str
+        assert "Request failed" in error_str
+        assert "Status: 404" in error_str
+        assert "Response JSON: {'error': 'Not found'}" in error_str
+
+    def test_exception_with_hints(self):
+        """Test that exceptions carry their hints properly."""
+        error = HudAuthenticationError("API key missing")
+
+        assert len(error.hints) == 1
+        assert error.hints[0] == HUD_API_KEY_MISSING
+        assert error.hints[0].title == "HUD API key required"
+        assert "Set HUD_API_KEY environment variable" in error.hints[0].tips[0]
+
+    def test_exception_type_preservation(self):
+        """Test that exception types are preserved through conversion."""
+        test_cases = [
+            ("Client not initialized", HudClientError),
+            ("Invalid JSON config", HudConfigError),
+            ("Tool 'test' not found", HudToolNotFoundError),
+            ("API key missing for HUD", HudAuthenticationError),
+            ("Rate limit exceeded", HudRateLimitError),
+            (TimeoutError("Timeout"), HudTimeoutError),
+        ]
+
+        for error_msg, expected_type in test_cases:
+            try:
+                if isinstance(error_msg, Exception):
+                    raise error_msg
+                else:
+                    raise ValueError(error_msg)
+            except Exception as e:
+                with pytest.raises(expected_type):
+                    raise HudException from e
+
+
+class TestEdgeCases:
+    """Test edge cases and error conditions."""
+
+    def test_none_exception_handling(self):
+        """Test handling when no exception context exists."""
+        # When there's no active exception, should create normal HudException
+        error = HudException("No chained exception")
+        assert type(error) is HudException
+        assert str(error) == "No chained exception"
+
+    def test_baseexception_not_converted(self):
+        """Test that BaseException (not Exception) is not converted."""
+        try:
+            raise KeyboardInterrupt("User interrupted")
+        except BaseException:
+            # Should not attempt to convert BaseException
+            error = HudException("Interrupted")
+            assert type(error) is HudException
+
+    def test_empty_error_message(self):
+        """Test handling of empty error messages."""
+        try:
+            raise ValueError("")
+        except Exception as e:
+            with pytest.raises(HudException) as exc_info:
+                raise HudException from e
+
+            # Should still have some message
+            assert str(exc_info.value) != ""
+
+    def test_circular_exception_chain(self):
+        """Test that we don't create circular exception chains."""
+        original = HudAuthenticationError("Original")
+
+        try:
+            raise original
+        except HudException as e:
+            # Raising HudException from HudException should not re-wrap
+            with pytest.raises(HudAuthenticationError) as exc_info:
+                raise HudException from e
+
+            assert exc_info.value is original

hud/tools/__init__.py

@@ -9,6 +9,7 @@ from .bash import BashTool
 from .edit import EditTool
 from .playwright import PlaywrightTool
 from .response import ResponseTool
+from .submit import SubmitTool
 
 if TYPE_CHECKING:
     from .computer import AnthropicComputerTool, HudComputerTool, OpenAIComputerTool
@@ -23,6 +24,7 @@ __all__ = [
     "OpenAIComputerTool",
     "PlaywrightTool",
     "ResponseTool",
+    "SubmitTool",
 ]
 
 

hud/tools/executors/tests/test_base_executor.py

@@ -361,5 +361,5 @@ class TestLazyImports:
         """Test lazy import with invalid attribute name."""
         import hud.tools.executors as executors_module
 
-        with pytest.raises(AttributeError, match="module '.*' has no attribute 'InvalidExecutor'"):
+        with pytest.raises(AttributeError, match=r"module '.*' has no attribute 'InvalidExecutor'"):
             _ = executors_module.InvalidExecutor

hud/tools/executors/xdo.py

@@ -175,7 +175,7 @@ class XDOExecutor(BaseExecutor):
 
         screenshot_cmd = f"{self._display_prefix}scrot -p {screenshot_path}"
 
-        returncode, _, stderr = await run(screenshot_cmd)
+        returncode, _, _stderr = await run(screenshot_cmd)
 
         if returncode == 0 and screenshot_path.exists():
             try:

hud/tools/grounding/__init__.py

@@ -0,0 +1,13 @@
+"""Grounding module for visual element detection and coordinate resolution."""
+
+from __future__ import annotations
+
+from .config import GrounderConfig
+from .grounded_tool import GroundedComputerTool
+from .grounder import Grounder
+
+__all__ = [
+    "GroundedComputerTool",
+    "Grounder",
+    "GrounderConfig",
+]