ref(api): tighten event serializer response types (#119351)

Add some slightly more accurate types to docs + dict fields

Co-authored-by: Claude <noreply@anthropic.com>

Author: cvxluo

src/sentry/api/serializers/models/event.py

@@ -4,7 +4,7 @@
 from collections import defaultdict
 from collections.abc import Sequence
 from datetime import datetime, timezone
-from typing import Any, TypedDict
+from typing import Any, NotRequired, TypedDict
 
 import sentry_sdk
 import sqlparse
@@ -18,10 +18,11 @@
 from sentry.api.serializers.types import GroupEventReleaseSerializerResponse
 from sentry.eventtypes import EventTypeStr
 from sentry.grouping.api import GroupingConfig
+from sentry.interfaces.sdk import EventSdkApiContext
 from sentry.interfaces.user import EventUserApiContext
 from sentry.issues.issue_occurrence import IssueOccurrenceResponse
 from sentry.models.eventattachment import EventAttachment
-from sentry.models.eventerror import EventError
+from sentry.models.eventerror import EventError, EventErrorApiContext
 from sentry.models.release import Release
 from sentry.models.userreport import UserReport
 from sentry.sdk_updates import SdkSetupState, get_suggested_updates
@@ -54,6 +55,11 @@ class EventTag(EventTagOptional):
     value: str
 
 
+class MeasurementValue(TypedDict):
+    value: float
+    unit: NotRequired[str | None]
+
+
 def get_crash_files(events):
     event_ids = [x.event_id for x in events if x.platform == "native"]
     if event_ids:
@@ -161,12 +167,12 @@ class BaseEventSerializerResponse(TypedDict):
     size: int | None
     entries: list[Any]
     dist: str | None
-    sdk: dict[str, str]
+    sdk: EventSdkApiContext | None
     context: dict[str, Any] | None
     packages: dict[str, Any]
     type: EventTypeStr
-    metadata: Any
-    errors: list[Any]
+    metadata: dict[str, Any]
+    errors: list[EventErrorApiContext]
     occurrence: IssueOccurrenceResponse | None
     _meta: dict[str, Any]
 
@@ -180,10 +186,10 @@ class ErrorEventFields(TypedDict, total=False):
 
 
 class TransactionEventFields(TypedDict, total=False):
-    startTimestamp: datetime
-    endTimestamp: datetime
-    measurements: Any
-    breakdowns: Any
+    startTimestamp: float
+    endTimestamp: float
+    measurements: dict[str, MeasurementValue] | None
+    breakdowns: dict[str, dict[str, MeasurementValue]] | None
 
 
 class EventSerializerResponse(
@@ -600,7 +606,7 @@ def serialize(self, obj, attrs, user, **kwargs):
         "platform": str | None,
         "dateCreated": datetime,
         "crashFile": str | None,
-        "metadata": dict[str, Any] | None,
+        "metadata": dict[str, Any],
     },
 )
 

src/sentry/apidocs/examples/event_examples.py

@@ -2,9 +2,13 @@
 
 from drf_spectacular.utils import OpenApiExample
 
-from sentry.api.serializers.models.event import EventSerializerResponse, GroupEventDetailsResponse
+from sentry.api.serializers.models.event import (
+    EventSerializerResponse,
+    GroupEventDetailsResponse,
+    SimpleEventSerializerResponse,
+)
 
-SIMPLE_EVENT = {
+SIMPLE_EVENT: SimpleEventSerializerResponse = {
     "eventID": "9fac2ceed9344f2bbfdd1fdacb0ed9b1",
     "tags": [
         {"key": "browser", "value": "Chrome 60.0"},
@@ -16,7 +20,7 @@
         {"key": "release", "value": "17642328ead24b51867165985996d04b29310337"},
         {"key": "server_name", "value": "web1.example.com"},
     ],
-    "dateCreated": "2020-09-11T17:46:36Z",
+    "dateCreated": datetime.fromisoformat("2020-09-11T17:46:36Z"),
     "user": None,
     "message": "",
     "title": "This is an example Python exception",
@@ -28,7 +32,10 @@
     "location": "example.py:123",
     "culprit": "/books/new/",
     "projectID": "49271",
-    "metadata": None,
+    "metadata": {
+        "type": "ExampleException",
+        "value": "This is an example Python exception",
+    },
 }
 
 GROUP_EVENT: GroupEventDetailsResponse = {

src/sentry/apidocs/examples/organization_examples.py

@@ -956,7 +956,7 @@ class OrganizationExamples:
                     "packages": {"my.package": "1.0.0"},
                     "platform": "python",
                     "projectID": "1",
-                    "sdk": {},
+                    "sdk": {"name": "sentry.python", "version": "2.0.0"},
                     "size": 7055,
                     "tags": [
                         {"key": "browser", "value": "Chrome 28.0"},

src/sentry/interfaces/sdk.py

@@ -1,9 +1,16 @@
 __all__ = ("Sdk",)
 
+from typing import TypedDict
+
 from sentry.interfaces.base import Interface
 from sentry.utils.json import prune_empty_keys
 
 
+class EventSdkApiContext(TypedDict):
+    name: str | None
+    version: str | None
+
+
 class Sdk(Interface):
     """
     The SDK used to transmit this event.
@@ -38,7 +45,7 @@ def to_json(self):
             }
         )
 
-    def get_api_context(self, is_public=False, platform=None):
+    def get_api_context(self, is_public=False, platform=None) -> EventSdkApiContext:
         return {"name": self.name, "version": self.version}
 
     def get_api_meta(self, meta, is_public=False, platform=None):

src/sentry/models/eventerror.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import enum
+from typing import Any, TypedDict
 
 
 class EventErrorType(enum.StrEnum):
@@ -60,6 +61,12 @@ class EventErrorType(enum.StrEnum):
     PROGUARD_MISSING_LINENO = "proguard_missing_lineno"
 
 
+class EventErrorApiContext(TypedDict):
+    type: str
+    message: str
+    data: dict[str, Any]
+
+
 class EventError:
     _messages: dict[str, str] = {
         EventErrorType.UNKNOWN_ERROR: "Unknown error",
@@ -125,5 +132,5 @@ def data(self):
     def message(self):
         return self._messages.get(self._data["type"], self._messages["unknown_error"])
 
-    def get_api_context(self):
+    def get_api_context(self) -> EventErrorApiContext:
         return {"type": self.type, "message": self.message, "data": self.data}