hud-python 0.4.52__py3-none-any.whl → 0.4.54__py3-none-any.whl

hud/shared/tests/test_exceptions.py

@@ -17,7 +17,6 @@ from hud.shared.exceptions import (
     HudClientError,
     HudConfigError,
     HudException,
-    HudMCPError,
     HudRateLimitError,
     HudRequestError,
     HudTimeoutError,
@@ -27,6 +26,7 @@ from hud.shared.hints import (
     CLIENT_NOT_INITIALIZED,
     HUD_API_KEY_MISSING,
     INVALID_CONFIG,
+    PRO_PLAN_REQUIRED,
     RATE_LIMIT_HIT,
     TOOL_NOT_FOUND,
 )
@@ -157,25 +157,23 @@ class TestHudExceptionAutoConversion:
             assert str(exc_info.value) == "Async operation timed out"
 
     def test_generic_error_remains_hudexception(self):
-        """Test that unmatched errors remain as base HudException."""
+        """Uncategorized errors become base HudException with original message."""
         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
+            # Should be base HudException, not subclass
             assert type(exc_info.value) is HudException
-            assert exc_info.value.hints == []
+            assert str(exc_info.value) == "Some random error"
 
     def test_custom_message_override(self):
-        """Test that custom message overrides the original."""
+        """Custom message should be used for categorized errors."""
         try:
-            raise ValueError("Original error")
+            raise ValueError("Client not initialized - call initialize() first")
         except Exception as e:
-            with pytest.raises(HudException) as exc_info:
+            with pytest.raises(HudClientError) 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):
@@ -205,6 +203,22 @@ class TestHudRequestError:
         error = HudRequestError("Forbidden", status_code=403)
         assert HUD_API_KEY_MISSING in error.hints
 
+    def test_403_pro_plan_message_sets_pro_hint(self):
+        """403 with Pro wording should map to PRO_PLAN_REQUIRED, not auth."""
+        error = HudRequestError("Feature requires Pro plan", status_code=403)
+        assert PRO_PLAN_REQUIRED in error.hints
+        assert HUD_API_KEY_MISSING not in error.hints
+
+    def test_403_pro_plan_detail_sets_pro_hint(self):
+        """403 with detail indicating Pro should map to PRO_PLAN_REQUIRED."""
+        error = HudRequestError(
+            "Forbidden",
+            status_code=403,
+            response_json={"detail": "Requires Pro plan"},
+        )
+        assert PRO_PLAN_REQUIRED in error.hints
+        assert HUD_API_KEY_MISSING not 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)
@@ -244,23 +258,19 @@ class TestMCPErrorHandling:
     @pytest.mark.asyncio
     async def test_mcp_error_handling(self):
         """Test that McpError is handled appropriately."""
-
-        # Create a mock McpError class
-        class McpError(Exception):
-            pass
-
-        # Create a mock MCP error
-        mcp_error = McpError("MCP protocol error: Unknown method")
+        # Create a dynamic class named "McpError" to trigger name-based detection
+        McpError = type("McpError", (Exception,), {})
 
         try:
-            raise mcp_error
+            raise McpError("MCP protocol error: Unknown method")
         except Exception as e:
             # This would typically be caught in the client code
             # and re-raised as HudException
-            with pytest.raises(HudMCPError) as exc_info:
+            with pytest.raises(HudException) as exc_info:
                 raise HudException from e
 
             assert "MCP protocol error" in str(exc_info.value)
+            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)."""
@@ -353,6 +363,7 @@ class TestExceptionRendering:
         assert len(error.hints) == 1
         assert error.hints[0] == HUD_API_KEY_MISSING
         assert error.hints[0].title == "HUD API key required"
+        # Hint copy evolved; keep the assertion robust to minor copy changes
         assert "Set HUD_API_KEY" in error.hints[0].tips[0]
 
     def test_exception_type_preservation(self):
@@ -397,16 +408,13 @@ class TestEdgeCases:
             assert type(error) is HudException
 
     def test_empty_error_message(self):
-        """Test handling of empty error messages."""
+        """Empty message still results in a HudException instance."""
         try:
             raise ValueError("")
         except Exception as e:
-            with pytest.raises(HudException) as exc_info:
+            with pytest.raises(HudException):
                 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")

hud/shared/tests/test_hints.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from hud.shared.hints import (
+    CLIENT_NOT_INITIALIZED,
+    ENV_VAR_MISSING,
+    HUD_API_KEY_MISSING,
+    INVALID_CONFIG,
+    MCP_SERVER_ERROR,
+    RATE_LIMIT_HIT,
+    TOOL_NOT_FOUND,
+    Hint,
+    render_hints,
+)
+
+
+def test_hint_objects_basic():
+    assert HUD_API_KEY_MISSING.title and isinstance(HUD_API_KEY_MISSING.tips, list)
+    assert RATE_LIMIT_HIT.code == "RATE_LIMIT"
+    assert TOOL_NOT_FOUND.title.startswith("Tool")
+    assert CLIENT_NOT_INITIALIZED.message
+    assert ENV_VAR_MISSING.command_examples is not None
+
+
+def test_all_hint_constants():
+    """Test that all predefined hint constants have required fields."""
+    hints = [
+        HUD_API_KEY_MISSING,
+        RATE_LIMIT_HIT,
+        TOOL_NOT_FOUND,
+        CLIENT_NOT_INITIALIZED,
+        INVALID_CONFIG,
+        ENV_VAR_MISSING,
+        MCP_SERVER_ERROR,
+    ]
+
+    for hint in hints:
+        assert hint.title
+        assert hint.message
+        assert hint.code
+
+
+def test_hint_creation():
+    """Test creating a custom Hint."""
+    hint = Hint(
+        title="Test Hint",
+        message="This is a test",
+        tips=["Tip 1", "Tip 2"],
+        docs_url="https://example.com",
+        command_examples=["command 1"],
+        code="TEST_CODE",
+        context=["test", "custom"],
+    )
+
+    assert hint.title == "Test Hint"
+    assert hint.message == "This is a test"
+    assert hint.tips and len(hint.tips) == 2
+    assert hint.docs_url == "https://example.com"
+    assert hint.command_examples and len(hint.command_examples) == 1
+    assert hint.code == "TEST_CODE"
+    assert hint.context and "test" in hint.context
+
+
+def test_hint_minimal():
+    """Test creating a minimal Hint with only required fields."""
+    hint = Hint(title="Minimal", message="Just basics")
+
+    assert hint.title == "Minimal"
+    assert hint.message == "Just basics"
+    assert hint.tips is None
+    assert hint.docs_url is None
+    assert hint.command_examples is None
+    assert hint.code is None
+    assert hint.context is None
+
+
+def test_render_hints_none():
+    """Test that render_hints handles None gracefully."""
+    # Should not raise
+    render_hints(None)
+
+
+def test_render_hints_empty_list():
+    """Test that render_hints handles empty list gracefully."""
+    # Should not raise
+    render_hints([])
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_with_tips(mock_console):
+    """Test rendering hints with tips."""
+    render_hints([HUD_API_KEY_MISSING])
+
+    # Should call warning for title/message
+    mock_console.warning.assert_called()
+    # Should call info for tips
+    assert mock_console.info.call_count >= 1
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_with_command_examples(mock_console):
+    """Test rendering hints with command examples."""
+    render_hints([ENV_VAR_MISSING])
+
+    # Should call command_example
+    mock_console.command_example.assert_called()
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_with_docs_url(mock_console):
+    """Test rendering hints with documentation URL."""
+    hint = Hint(
+        title="Test",
+        message="Test message",
+        docs_url="https://docs.example.com",
+    )
+
+    render_hints([hint])
+
+    # Should call link for docs URL
+    mock_console.link.assert_called_with("https://docs.example.com")
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_same_title_and_message(mock_console):
+    """Test rendering hints when title equals message."""
+    hint = Hint(title="Same", message="Same")
+
+    render_hints([hint])
+
+    # Should only call warning once with just the message
+    mock_console.warning.assert_called_once_with("Same")
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_different_title_and_message(mock_console):
+    """Test rendering hints when title differs from message."""
+    hint = Hint(title="Title", message="Different message")
+
+    render_hints([hint])
+
+    # Should call warning with both title and message
+    mock_console.warning.assert_called_once()
+    call_args = mock_console.warning.call_args[0][0]
+    assert "Title" in call_args
+    assert "Different message" in call_args
+
+
+def test_render_hints_with_custom_design():
+    """Test rendering hints with custom design object."""
+    custom_design = MagicMock()
+
+    hint = Hint(title="Test", message="Message")
+    # Should not raise when custom design is provided
+    render_hints([hint], design=custom_design)
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_handles_exception(mock_console):
+    """Test that render_hints handles exceptions gracefully."""
+    mock_console.warning.side_effect = Exception("Test error")
+
+    hint = Hint(title="Test", message="Message")
+
+    # Should not raise, just log warning
+    render_hints([hint])

hud/telemetry/tests/test_async_context.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from hud.telemetry.async_context import async_job, async_trace
+
+
+@pytest.mark.asyncio
+async def test_async_trace_basic():
+    """Test basic AsyncTrace usage."""
+    with (
+        patch("hud.telemetry.async_context.OtelTrace") as mock_otel,
+        patch("hud.telemetry.async_context.track_task"),
+        patch("hud.telemetry.async_context._print_trace_url"),
+        patch("hud.telemetry.async_context._print_trace_complete_url"),
+    ):
+        mock_otel_instance = MagicMock()
+        mock_otel.return_value = mock_otel_instance
+
+        async with async_trace("Test Task") as trace_obj:
+            assert trace_obj.name == "Test Task"
+            assert trace_obj.id is not None
+
+
+@pytest.mark.asyncio
+async def test_async_trace_with_job_id():
+    """Test AsyncTrace with job_id parameter."""
+    with (
+        patch("hud.telemetry.async_context.OtelTrace") as mock_otel,
+        patch("hud.telemetry.async_context.track_task"),
+    ):
+        mock_otel_instance = MagicMock()
+        mock_otel.return_value = mock_otel_instance
+
+        async with async_trace("Test", job_id="job-123") as trace_obj:
+            assert trace_obj.job_id == "job-123"
+
+
+@pytest.mark.asyncio
+async def test_async_trace_with_task_id():
+    """Test AsyncTrace with task_id parameter."""
+    with (
+        patch("hud.telemetry.async_context.OtelTrace") as mock_otel,
+        patch("hud.telemetry.async_context.track_task"),
+    ):
+        mock_otel_instance = MagicMock()
+        mock_otel.return_value = mock_otel_instance
+
+        async with async_trace("Test", task_id="task-456") as trace_obj:
+            assert trace_obj.task_id == "task-456"
+
+
+@pytest.mark.asyncio
+async def test_async_trace_prints_url_without_job():
+    """Test AsyncTrace prints URL when not part of a job."""
+    with (
+        patch("hud.telemetry.async_context.settings") as mock_settings,
+        patch("hud.telemetry.async_context.OtelTrace") as mock_otel,
+        patch("hud.telemetry.async_context.track_task"),
+        patch("hud.telemetry.async_context._print_trace_url") as mock_print_url,
+    ):
+        mock_settings.telemetry_enabled = True
+        mock_settings.api_key = "test-key"
+        mock_otel_instance = MagicMock()
+        mock_otel.return_value = mock_otel_instance
+
+        async with async_trace("Test", job_id=None):
+            pass
+
+        # Should print trace URL
+        mock_print_url.assert_called_once()
+
+
+@pytest.mark.asyncio
+async def test_async_trace_no_print_url_with_job():
+    """Test AsyncTrace doesn't print URL when part of a job."""
+    with (
+        patch("hud.telemetry.async_context.settings") as mock_settings,
+        patch("hud.telemetry.async_context.OtelTrace") as mock_otel,
+        patch("hud.telemetry.async_context.track_task"),
+        patch("hud.telemetry.async_context._print_trace_url") as mock_print_url,
+    ):
+        mock_settings.telemetry_enabled = True
+        mock_settings.api_key = "test-key"
+        mock_otel_instance = MagicMock()
+        mock_otel.return_value = mock_otel_instance
+
+        async with async_trace("Test", job_id="job-123"):
+            pass
+
+        # Should NOT print trace URL when job_id is set
+        mock_print_url.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_async_trace_with_exception():
+    """Test AsyncTrace handles exceptions."""
+    with (
+        patch("hud.telemetry.async_context.settings") as mock_settings,
+        patch("hud.telemetry.async_context.OtelTrace") as mock_otel,
+        patch("hud.telemetry.async_context.track_task"),
+        patch("hud.telemetry.async_context._print_trace_complete_url") as mock_print,
+    ):
+        # Enable telemetry for this test
+        mock_settings.telemetry_enabled = True
+        mock_settings.api_key = "test-key"
+
+        mock_otel_instance = MagicMock()
+        mock_otel.return_value = mock_otel_instance
+
+        with pytest.raises(ValueError):
+            async with async_trace("Test"):
+                raise ValueError("Test error")
+
+        # Should have been called with error_occurred keyword arg
+        mock_print.assert_called_once()
+        call_kwargs = mock_print.call_args[1]
+        assert call_kwargs["error_occurred"] is True
+
+
+@pytest.mark.asyncio
+async def test_async_job_basic():
+    """Test basic AsyncJob usage."""
+    with (
+        patch("hud.telemetry.async_context.track_task"),
+        patch("hud.telemetry.async_context._print_job_url"),
+        patch("hud.telemetry.async_context._print_job_complete_url"),
+    ):
+        async with async_job("Test Job") as job_obj:
+            assert job_obj.name == "Test Job"
+            assert job_obj.id is not None
+
+
+@pytest.mark.asyncio
+async def test_async_job_with_metadata():
+    """Test AsyncJob with metadata."""
+    with (
+        patch("hud.telemetry.async_context.track_task"),
+        patch("hud.telemetry.async_context._print_job_url"),
+        patch("hud.telemetry.async_context._print_job_complete_url"),
+    ):
+        async with async_job("Test", metadata={"key": "value"}) as job_obj:
+            assert job_obj.metadata == {"key": "value"}
+
+
+@pytest.mark.asyncio
+async def test_async_job_with_dataset_link():
+    """Test AsyncJob with dataset_link."""
+    with (
+        patch("hud.telemetry.async_context.track_task"),
+        patch("hud.telemetry.async_context._print_job_url"),
+        patch("hud.telemetry.async_context._print_job_complete_url"),
+    ):
+        async with async_job("Test", dataset_link="test/dataset") as job_obj:
+            assert job_obj.dataset_link == "test/dataset"
+
+
+@pytest.mark.asyncio
+async def test_async_job_with_custom_job_id():
+    """Test AsyncJob with custom job_id."""
+    with (
+        patch("hud.telemetry.async_context.track_task"),
+        patch("hud.telemetry.async_context._print_job_url"),
+        patch("hud.telemetry.async_context._print_job_complete_url"),
+    ):
+        async with async_job("Test", job_id="custom-id") as job_obj:
+            assert job_obj.id == "custom-id"
+
+
+@pytest.mark.asyncio
+async def test_async_job_with_exception():
+    """Test AsyncJob handles exceptions."""
+    with (
+        patch("hud.telemetry.async_context.track_task"),
+        patch("hud.telemetry.async_context._print_job_url"),
+        patch("hud.telemetry.async_context._print_job_complete_url") as mock_print,
+    ):
+        with pytest.raises(ValueError):
+            async with async_job("Test"):
+                raise ValueError("Job error")
+
+        # Should print with error_occurred keyword arg
+        mock_print.assert_called_once()
+        call_kwargs = mock_print.call_args[1]
+        assert call_kwargs["error_occurred"] is True
+
+
+@pytest.mark.asyncio
+async def test_async_job_status_updates():
+    """Test AsyncJob sends status updates."""
+    with (
+        patch("hud.telemetry.async_context.settings") as mock_settings,
+        patch("hud.telemetry.async_context.track_task") as mock_track,
+        patch("hud.telemetry.async_context._print_job_url"),
+        patch("hud.telemetry.async_context._print_job_complete_url"),
+    ):
+        mock_settings.telemetry_enabled = True
+        mock_settings.api_key = "test-key"
+        mock_settings.hud_telemetry_url = "https://test.com"
+
+        async with async_job("Test"):
+            pass
+
+        # Should have called track_task twice (running and completed)
+        assert mock_track.call_count == 2
+
+
+@pytest.mark.asyncio
+async def test_async_job_includes_dataset_link_in_status():
+    """Test AsyncJob includes dataset_link in status updates."""
+    with (
+        patch("hud.telemetry.async_context.settings") as mock_settings,
+        patch("hud.telemetry.async_context.track_task"),
+        patch("hud.telemetry.async_context.make_request", new_callable=AsyncMock),
+        patch("hud.telemetry.async_context._print_job_url"),
+        patch("hud.telemetry.async_context._print_job_complete_url"),
+    ):
+        mock_settings.telemetry_enabled = True
+        mock_settings.api_key = "test-key"
+        mock_settings.hud_telemetry_url = "https://test.com"
+
+        async with async_job("Test", dataset_link="test/dataset"):
+            pass
+
+
+@pytest.mark.asyncio
+async def test_async_trace_non_root():
+    """Test AsyncTrace with root=False."""
+    with (
+        patch("hud.telemetry.async_context.OtelTrace") as mock_otel,
+        patch("hud.telemetry.async_context.track_task") as mock_track,
+    ):
+        mock_otel_instance = MagicMock()
+        mock_otel.return_value = mock_otel_instance
+
+        async with async_trace("Test", root=False):
+            pass
+
+        # Should not track status updates for non-root traces
+        mock_track.assert_not_called()