ref(api): Type hinting for start_transaction kwargs (#2796)

This PR adds be type hints for the `**kwargs` that can be passed to `sentry_sdk.start_transaction`, thereby clearly documenting the parameters that can be passed directly in the code.

Ref getsentry/sentry-docs#5082

  - We intend to add to the docs page at least the most useful arguments defined in the `TransactionKwargs` type that this PR introduces.

---------

Co-authored-by: Anton Pirker <[email protected]>

Author: szokeasaurusrex

sentry_sdk/api.py

@@ -17,6 +17,8 @@
     from typing import ContextManager
     from typing import Union
 
+    from typing_extensions import Unpack
+
     from sentry_sdk.client import BaseClient
     from sentry_sdk._types import (
         Event,
@@ -26,6 +28,7 @@
         ExcInfo,
         MeasurementUnit,
     )
+    from sentry_sdk.scope import StartTransactionKwargs
     from sentry_sdk.tracing import Span
 
     T = TypeVar("T")
@@ -278,7 +281,7 @@ def start_span(
 @scopemethod
 def start_transaction(
     transaction=None,  # type: Optional[Transaction]
-    **kwargs,  # type: Any
+    **kwargs,  # type: Unpack[StartTransactionKwargs]
 ):
     # type: (...) -> Union[Transaction, NoOpSpan]
     return Scope.get_current_scope().start_transaction(transaction, **kwargs)

sentry_sdk/hub.py

@@ -31,6 +31,8 @@
     from typing import TypeVar
     from typing import Union
 
+    from typing_extensions import Unpack
+
     from sentry_sdk.client import BaseClient
     from sentry_sdk.integrations import Integration
     from sentry_sdk._types import (
@@ -41,6 +43,7 @@
         ExcInfo,
     )
     from sentry_sdk.consts import ClientConstructor
+    from sentry_sdk.scope import StartTransactionKwargs
 
     T = TypeVar("T")
 
@@ -468,7 +471,7 @@ def start_span(self, instrumenter=INSTRUMENTER.SENTRY, **kwargs):
     def start_transaction(
         self, transaction=None, instrumenter=INSTRUMENTER.SENTRY, **kwargs
     ):
-        # type: (Optional[Transaction], str, Any) -> Union[Transaction, NoOpSpan]
+        # type: (Optional[Transaction], str, Unpack[StartTransactionKwargs]) -> Union[Transaction, NoOpSpan]
         """
         .. deprecated:: 2.0.0
             This function is deprecated and will be removed in a future release.
@@ -501,7 +504,8 @@ def start_transaction(
 
         # For backwards compatibility, we allow passing the scope as the hub.
         # We need a major release to make this nice. (if someone searches the code: deprecated)
-        kwargs["hub"] = scope
+        # Type checking disabled for this line because deprecated keys are not allowed in the type signature.
+        kwargs["hub"] = scope  # type: ignore
 
         return scope.start_transaction(
             transaction=transaction, instrumenter=instrumenter, **kwargs

sentry_sdk/scope.py

@@ -49,6 +49,8 @@
     from typing import TypeVar
     from typing import Union
 
+    from typing_extensions import Unpack
+
     from sentry_sdk._types import (
         Breadcrumb,
         BreadcrumbHint,
@@ -57,11 +59,18 @@
         EventProcessor,
         ExcInfo,
         Hint,
+        SamplingContext,
         Type,
     )
 
+    from sentry_sdk.tracing import TransactionKwargs
+
     import sentry_sdk
 
+    class StartTransactionKwargs(TransactionKwargs, total=False):
+        client: Optional["sentry_sdk.Client"]
+        custom_sampling_context: SamplingContext
+
     P = ParamSpec("P")
     R = TypeVar("R")
 
@@ -935,7 +944,7 @@ def add_breadcrumb(self, crumb=None, hint=None, **kwargs):
     def start_transaction(
         self, transaction=None, instrumenter=INSTRUMENTER.SENTRY, **kwargs
     ):
-        # type: (Optional[Transaction], str, Any) -> Union[Transaction, NoOpSpan]
+        # type: (Optional[Transaction], str, Unpack[StartTransactionKwargs]) -> Union[Transaction, NoOpSpan]
         """
         Start and return a transaction.
 
@@ -971,9 +980,13 @@ def start_transaction(
 
         custom_sampling_context = kwargs.pop("custom_sampling_context", {})
 
+        # kwargs at this point has type TransactionKwargs, since we have removed
+        # the client and custom_sampling_context from it.
+        transaction_kwargs = kwargs  # type: TransactionKwargs
+
         # if we haven't been given a transaction, make one
         if transaction is None:
-            transaction = Transaction(**kwargs)
+            transaction = Transaction(**transaction_kwargs)
 
         # use traces_sample_rate, traces_sampler, and/or inheritance to make a
         # sampling decision

sentry_sdk/tracing.py

@@ -22,12 +22,35 @@
     from typing import Union
     from typing import TypeVar
 
+    from typing_extensions import TypedDict, Unpack
+
     P = ParamSpec("P")
     R = TypeVar("R")
 
     import sentry_sdk.profiler
     from sentry_sdk._types import Event, MeasurementUnit, SamplingContext
 
+    class SpanKwargs(TypedDict, total=False):
+        trace_id: str
+        span_id: str
+        parent_span_id: str
+        same_process_as_parent: bool
+        sampled: bool
+        op: str
+        description: str
+        # hub: Optional[sentry_sdk.Hub] is deprecated, and therefore omitted here!
+        status: str
+        # transaction: str is deprecated, and therefore omitted here!
+        containing_transaction: Optional["Transaction"]
+        start_timestamp: Optional[Union[datetime, float]]
+        scope: "sentry_sdk.Scope"
+
+    class TransactionKwargs(SpanKwargs, total=False):
+        name: str
+        source: str
+        parent_sampled: bool
+        baggage: "Baggage"
+
 
 BAGGAGE_HEADER_NAME = "baggage"
 SENTRY_TRACE_HEADER_NAME = "sentry-trace"
@@ -252,7 +275,7 @@ def start_child(self, instrumenter=INSTRUMENTER.SENTRY, **kwargs):
             trace_id=self.trace_id,
             parent_span_id=self.span_id,
             containing_transaction=self.containing_transaction,
-            **kwargs
+            **kwargs,
         )
 
         span_recorder = (
@@ -267,7 +290,7 @@ def start_child(self, instrumenter=INSTRUMENTER.SENTRY, **kwargs):
     def continue_from_environ(
         cls,
         environ,  # type: Mapping[str, str]
-        **kwargs  # type: Any
+        **kwargs,  # type: Any
     ):
         # type: (...) -> Transaction
         """
@@ -293,7 +316,7 @@ def continue_from_environ(
     def continue_from_headers(
         cls,
         headers,  # type: Mapping[str, str]
-        **kwargs  # type: Any
+        **kwargs,  # type: Any
     ):
         # type: (...) -> Transaction
         """
@@ -349,7 +372,7 @@ def iter_headers(self):
     def from_traceparent(
         cls,
         traceparent,  # type: Optional[str]
-        **kwargs  # type: Any
+        **kwargs,  # type: Any
     ):
         # type: (...) -> Optional[Transaction]
         """
@@ -559,7 +582,7 @@ def __init__(
         parent_sampled=None,  # type: Optional[bool]
         baggage=None,  # type: Optional[Baggage]
         source=TRANSACTION_SOURCE_CUSTOM,  # type: str
-        **kwargs  # type: Any
+        **kwargs,  # type: Unpack[SpanKwargs]
     ):
         # type: (...) -> None
         """Constructs a new Transaction.
@@ -583,7 +606,7 @@ def __init__(
                 "Deprecated: use Transaction(name=...) to create transactions "
                 "instead of Span(transaction=...)."
             )
-            name = kwargs.pop("transaction")
+            name = kwargs.pop("transaction")  # type: ignore
 
         super().__init__(**kwargs)