Extend payload-based detail access pattern to TimeoutError and activity.Info

- Replace ApplicationError.details_with_type_hints with get_detail(index, type_hint)
- Add TimeoutError.get_heartbeat_detail() with payload-based lazy loading
- Add activity.Info.get_heartbeat_detail() with payload-based access
- Make heartbeat_details properties that decode payloads on access
- Store raw payloads instead of decoded details to support type hints
- Update tests to use new get_detail method

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: tconley1428

temporalio/activity.py

@@ -26,6 +26,7 @@
     overload,
 )
 
+import temporalio.api.common.v1
 import temporalio.bridge
 import temporalio.bridge.proto
 import temporalio.bridge.proto.activity_task
@@ -101,7 +102,8 @@ class Info:
     activity_type: str
     attempt: int
     current_attempt_scheduled_time: datetime
-    heartbeat_details: Sequence[Any]
+    _heartbeat_payloads: Sequence[temporalio.api.common.v1.Payload]
+    _payload_converter: temporalio.converter.PayloadConverter
     heartbeat_timeout: timedelta | None
     is_local: bool
     schedule_to_close_timeout: timedelta | None
@@ -124,6 +126,34 @@ class Info:
 
     # TODO(cretz): Consider putting identity on here for "worker_id" for logger?
 
+    @property
+    def heartbeat_details(self) -> Sequence[Any]:
+        """Heartbeat details for the activity."""
+        return self._payload_converter.from_payloads(self._heartbeat_payloads, None)
+
+    def get_heartbeat_detail(self, index: int, type_hint: type | None = None) -> Any:
+        """Get a heartbeat detail by index with optional type hint.
+
+        Args:
+            index: Zero-based index of the heartbeat detail to retrieve.
+            type_hint: Optional type hint for deserialization.
+
+        Returns:
+            The heartbeat detail at the specified index.
+
+        Raises:
+            IndexError: If the index is out of range.
+        """
+        if index < 0 or index >= len(self._heartbeat_payloads):
+            raise IndexError(
+                f"Heartbeat detail index {index} out of range (0-{len(self._heartbeat_payloads)-1})"
+            )
+        # Convert single payload at the specified index
+        payload = self._heartbeat_payloads[index]
+        type_hints = [type_hint] if type_hint is not None else None
+        converted = self._payload_converter.from_payloads([payload], type_hints)
+        return converted[0] if converted else None
+
     def _logger_details(self) -> Mapping[str, Any]:
         return {
             "activity_id": self.activity_id,

temporalio/converter.py

@@ -1133,14 +1133,15 @@ def from_failure(
             )
         elif failure.HasField("timeout_failure_info"):
             timeout_info = failure.timeout_failure_info
-            err = temporalio.exceptions.TimeoutError(
+            err = temporalio.exceptions.TimeoutError._from_failure(
                 failure.message or "Timeout",
-                type=temporalio.exceptions.TimeoutType(int(timeout_info.timeout_type))
+                timeout_type=temporalio.exceptions.TimeoutType(
+                    int(timeout_info.timeout_type)
+                )
                 if timeout_info.timeout_type
                 else None,
-                last_heartbeat_details=payload_converter.from_payloads_wrapper(
-                    timeout_info.last_heartbeat_details
-                ),
+                heartbeat_payloads=timeout_info.last_heartbeat_details,
+                payload_converter=payload_converter,
             )
         elif failure.HasField("canceled_failure_info"):
             cancel_info = failure.canceled_failure_info

temporalio/exceptions.py

@@ -1,6 +1,7 @@
 """Common Temporal exceptions."""
 
 import asyncio
+import builtins
 import typing
 from collections.abc import Sequence
 from datetime import timedelta
@@ -144,20 +145,46 @@ def _from_failure(
     @property
     def details(self) -> Sequence[Any]:
         """User-defined details on the error."""
-        return self.details_with_type_hints()
-
-    def details_with_type_hints(
-        self, type_hints: list[type] | None = None
-    ) -> Sequence[Any]:
-        """User-defined details on the error with type hints for deserialization."""
         if self._payload_converter and self._payloads is not None:
             if not self._payloads or not self._payloads.payloads:
                 return []
-            return self._payload_converter.from_payloads(
-                self._payloads.payloads, type_hints
-            )
+            return self._payload_converter.from_payloads(self._payloads.payloads, None)
         return self._details
 
+    def get_detail(self, index: int, type_hint: type | None = None) -> Any:
+        """Get a detail by index with optional type hint.
+
+        Args:
+            index: Zero-based index of the detail to retrieve.
+            type_hint: Optional type hint for deserialization.
+
+        Returns:
+            The detail at the specified index.
+
+        Raises:
+            IndexError: If the index is out of range.
+        """
+        if (
+            self._payload_converter
+            and self._payloads is not None
+            and self._payloads.payloads
+        ):
+            if index < 0 or index >= len(self._payloads.payloads):
+                raise IndexError(
+                    f"Detail index {index} out of range (0-{len(self._payloads.payloads)-1})"
+                )
+            # Convert single payload at the specified index
+            payload = self._payloads.payloads[index]
+            type_hints = [type_hint] if type_hint is not None else None
+            converted = self._payload_converter.from_payloads([payload], type_hints)
+            return converted[0] if converted else None
+        else:
+            if index < 0 or index >= len(self._details):
+                raise IndexError(
+                    f"Detail index {index} out of range (0-{len(self._details)-1})"
+                )
+            return self._details[index]
+
     @property
     def type(self) -> str | None:
         """General error type."""
@@ -245,17 +272,82 @@ def __init__(
         super().__init__(message)
         self._type = type
         self._last_heartbeat_details = last_heartbeat_details
+        self._heartbeat_payloads: Payloads | None = None
+        self._payload_converter: "PayloadConverter | None" = None
 
     @property
     def type(self) -> TimeoutType | None:
         """Type of timeout error."""
         return self._type
 
+    @classmethod
+    def _from_failure(
+        cls,
+        message: str,
+        timeout_type: TimeoutType | None,
+        heartbeat_payloads: Payloads | None,
+        payload_converter: "PayloadConverter",
+    ) -> "TimeoutError":
+        """Create a TimeoutError from failure payloads (internal use only)."""
+        # Create instance using regular constructor first
+        instance = cls(
+            message,
+            type=timeout_type,
+            last_heartbeat_details=[],  # Will be overridden if payloads exist
+        )
+        # Override payloads and payload converter for lazy loading if payloads exist
+        if heartbeat_payloads is not None:
+            instance._heartbeat_payloads = heartbeat_payloads
+            instance._payload_converter = payload_converter
+        return instance
+
     @property
     def last_heartbeat_details(self) -> Sequence[Any]:
         """Last heartbeat details if this is for an activity heartbeat."""
+        if self._payload_converter and self._heartbeat_payloads is not None:
+            if not self._heartbeat_payloads.payloads:
+                return []
+            return self._payload_converter.from_payloads(
+                self._heartbeat_payloads.payloads, None
+            )
         return self._last_heartbeat_details
 
+    def get_heartbeat_detail(
+        self, index: int, type_hint: builtins.type | None = None
+    ) -> Any:
+        """Get a heartbeat detail by index with optional type hint.
+
+        Args:
+            index: Zero-based index of the heartbeat detail to retrieve.
+            type_hint: Optional type hint for deserialization.
+
+        Returns:
+            The heartbeat detail at the specified index.
+
+        Raises:
+            IndexError: If the index is out of range.
+        """
+        if (
+            self._payload_converter
+            and self._heartbeat_payloads is not None
+            and self._heartbeat_payloads.payloads
+        ):
+            if index < 0 or index >= len(self._heartbeat_payloads.payloads):
+                raise IndexError(
+                    f"Heartbeat detail index {index} out of range (0-{len(self._heartbeat_payloads.payloads)-1})"
+                )
+            # Convert single payload at the specified index
+            payload = self._heartbeat_payloads.payloads[index]
+            type_hints = [type_hint] if type_hint is not None else None
+            converted = self._payload_converter.from_payloads([payload], type_hints)
+            return converted[0] if converted else None
+        else:
+            if index < 0 or index >= len(self._last_heartbeat_details):
+                raise IndexError(
+                    f"Heartbeat detail index {index} out of range (0-{len(self._last_heartbeat_details)-1})"
+                )
+            return self._last_heartbeat_details[index]
+
 
 class ServerError(FailureError):
     """Error originating in the Temporal server."""

temporalio/testing/_activity.py

@@ -28,7 +28,8 @@
     activity_type="unknown",
     attempt=1,
     current_attempt_scheduled_time=_utc_zero,
-    heartbeat_details=[],
+    _heartbeat_payloads=[],
+    _payload_converter=temporalio.converter.DataConverter.default.payload_converter,
     heartbeat_timeout=None,
     is_local=False,
     schedule_to_close_timeout=timedelta(seconds=1),

temporalio/worker/_activity.py

@@ -527,19 +527,6 @@ async def _execute_activity(
         if not activity_def.name:
             args = [args]
 
-        # Convert heartbeat details
-        # TODO(cretz): Allow some way to configure heartbeat type hinting?
-        try:
-            heartbeat_details = (
-                []
-                if not start.heartbeat_details
-                else await data_converter.decode(start.heartbeat_details)
-            )
-        except Exception as err:
-            raise temporalio.exceptions.ApplicationError(
-                "Failed decoding heartbeat details", non_retryable=True
-            ) from err
-
         # Build info
         info = temporalio.activity.Info(
             activity_id=start.activity_id,
@@ -548,7 +535,8 @@ async def _execute_activity(
             current_attempt_scheduled_time=_proto_to_datetime(
                 start.current_attempt_scheduled_time
             ),
-            heartbeat_details=heartbeat_details,
+            _heartbeat_payloads=list(start.heartbeat_details),
+            _payload_converter=data_converter.payload_converter,
             heartbeat_timeout=_proto_to_non_zero_timedelta(start.heartbeat_timeout)
             if start.HasField("heartbeat_timeout")
             else None,

tests/test_converter.py

@@ -693,8 +693,8 @@ class MyCustomDetail:
     timestamp: datetime
 
 
-async def test_application_error_details_with_type_hints():
-    """Test ApplicationError details with type hints functionality."""
+async def test_application_error_get_detail():
+    """Test ApplicationError get_detail functionality."""
 
     # Test data
     detail_str = "error detail"
@@ -727,16 +727,22 @@ async def test_application_error_details_with_type_hints():
     assert details[2]["value"] == 42
     assert details[2]["timestamp"] == "2023-01-01T12:00:00"
 
-    # Test accessing details with type hints
-    typed_details = decoded_error.details_with_type_hints([str, int, MyCustomDetail])
-    assert len(typed_details) == 3
-    assert typed_details[0] == detail_str
-    assert typed_details[1] == detail_int
+    # Test accessing individual details with type hints
+    assert decoded_error.get_detail(0, str) == detail_str
+    assert decoded_error.get_detail(1, int) == detail_int
     # Custom object is properly reconstructed with type hint
-    assert isinstance(typed_details[2], MyCustomDetail)
-    assert typed_details[2].name == "test"
-    assert typed_details[2].value == 42
-    assert typed_details[2].timestamp == datetime(2023, 1, 1, 12, 0, 0)
+    custom_detail = decoded_error.get_detail(2, MyCustomDetail)
+    assert isinstance(custom_detail, MyCustomDetail)
+    assert custom_detail.name == "test"
+    assert custom_detail.value == 42
+    assert custom_detail.timestamp == datetime(2023, 1, 1, 12, 0, 0)
+
+    # Test accessing details without type hints using get_detail
+    assert decoded_error.get_detail(0) == detail_str
+    assert decoded_error.get_detail(1) == detail_int
+    dict_detail = decoded_error.get_detail(2)
+    assert isinstance(dict_detail, dict)
+    assert dict_detail["name"] == "test"
 
 
 async def test_application_error_details_empty():
@@ -751,34 +757,9 @@ async def test_application_error_details_empty():
 
     assert isinstance(decoded_error, ApplicationError)
     assert len(decoded_error.details) == 0
-    assert len(decoded_error.details_with_type_hints([])) == 0
-
-
-async def test_application_error_details_partial_type_hints():
-    """Test ApplicationError details with partial type hints."""
-
-    detail1 = "string detail"
-    detail2 = 456
-    detail3 = MyCustomDetail("partial", 99, datetime(2023, 6, 15, 9, 30, 0))
-
-    error = ApplicationError(
-        "Partial hints error", detail1, detail2, detail3, type="PartialHints"
-    )
-
-    failure = Failure()
-    converter = DataConverter.default
-    await converter.encode_failure(error, failure)
-    decoded_error = await converter.decode_failure(failure)
-
-    # Provide type hints for only the first two details
-    assert isinstance(decoded_error, ApplicationError)
-    typed_details = decoded_error.details_with_type_hints([str, int])
-    assert len(typed_details) == 3
-    assert typed_details[0] == detail1
-    assert typed_details[1] == detail2
-    # Third detail has no type hint, so it remains as dict
-    assert isinstance(typed_details[2], dict)
-    assert typed_details[2]["name"] == "partial"
+    # Test get_detail with out of range index
+    with pytest.raises(IndexError):
+        decoded_error.get_detail(0)
 
 
 async def test_application_error_details_direct_creation():
@@ -804,13 +785,12 @@ async def test_application_error_details_direct_creation():
     assert details[0] == detail1
     assert isinstance(details[1], dict)  # No type hint
 
-    # Test with type hints
-    typed_details = error.details_with_type_hints([str, MyCustomDetail])
-    assert len(typed_details) == 2
-    assert typed_details[0] == detail1
-    assert isinstance(typed_details[1], MyCustomDetail)
-    assert typed_details[1].name == "direct"
-    assert typed_details[1].value == 777
+    # Test get_detail method
+    assert error.get_detail(0, str) == detail1
+    custom_detail = error.get_detail(1, MyCustomDetail)
+    assert isinstance(custom_detail, MyCustomDetail)
+    assert custom_detail.name == "direct"
+    assert custom_detail.value == 777
 
 
 async def test_application_error_details_none_payload_converter():
@@ -824,10 +804,11 @@ async def test_application_error_details_none_payload_converter():
 
     # Both methods should return the same result - the raw details tuple
     details = error.details
-    typed_details = error.details_with_type_hints([str, int])
-
     assert details == (detail1, detail2)
-    assert typed_details == (detail1, detail2)
+
+    # Test get_detail method
+    assert error.get_detail(0) == detail1
+    assert error.get_detail(1) == detail2
 
 
 def test_application_error_details_edge_cases():
@@ -845,7 +826,8 @@ def test_application_error_details_edge_cases():
     )
 
     assert len(error.details) == 0
-    assert len(error.details_with_type_hints([str])) == 0
+    with pytest.raises(IndexError):
+        error.get_detail(0)
 
     # Test with non-Payloads details when payload_converter is set
     error2 = ApplicationError(
@@ -856,4 +838,5 @@ def test_application_error_details_edge_cases():
 
     # Should return the raw details since they're not Payloads
     assert error2.details == ("string", 123)
-    assert error2.details_with_type_hints([str, int]) == ("string", 123)
+    assert error2.get_detail(0) == "string"
+    assert error2.get_detail(1) == 123