ref(types): add partial type hints for SamplingContext

[NamitAdhikari]

Description

Adds type hints for SamplingContext to improve developer experience when implementing traces_sampler callback. Previously, SamplingContext was typed as Dict[str, Any], developers had no way to discover available fields without reading source code or inspecting field in runtime.

Motivation

While implementing custom transaction sampling logic to control which transactions are sent from the client, I noticed there were no type hints for the sampling_context parameter in traces_sampler callback. This made it difficult to know what fields were available without inspecting the sample_context in runtime using ipdb. This deteriorated developer experience.

Before

def traces_sampler(sampling_context):  # sampling_context: Dict[str, Any] - no autocomplete!
    # No idea what fields are available
    ...

After

def traces_sampler(sampling_context: SamplingContext):
    # Full autocomplete for transaction_context, asgi_scope, etc.
    transaction_name = sampling_context["transaction_context"]["name"]
    if sampling_context.get("asgi_scope"):
        # Handle ASGI-specific logic (in my case - FastAPI)
        ...

Issues

None for this PR - this is an enhancement for developer experience

Notes

• Testing Scope: Only ASGI, WSGI, AIOHTTP and Custom script was tested, others were added based on codebase analysis to pass mypy
• Union[SamplingContextTyped, dict[str, Any]] was added as type to SamplingContext to not break SDK specific internals, as well as allow developers to access integration-specific fields
• Future integrations that add custom sampling context fields should update SamplingContextTyped to maintain type safety.

Example Usage

def custom_traces_sampler(sampling_context: "SamplingContext"):
    if sampling_context["transaction_context"]["source"] != TransactionSource.URL:
        return 1.0

    scope = sampling_context.get("asgi_scope")
    if not scope:
        return 1.0

    # Filter out healthcheck endpoints
    path = scope["path"]
    if path.endswith("/health"):
        return 0.0  # Drop the transaction (don't sample)

    return 1.0

sentry_sdk.init(
    dsn="...",
    traces_sampler=custom_traces_sampler,
)

Reminders

• tox -e linters passed
• All imports placed in if TYPE_CHECKING: block (no runtime overhead)
• Follows Sentry conventional commit format (ref for refactor)
• Test typehints in IDE by installing package itself in existing project using pip install -e .

[github-actions]

Semver Impact of This PR

🟢 Patch (bug fixes)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

---

Bug Fixes 🐛

• fix(celery): Close the connection we're reading driver_type from by sentrivana in #5427

Internal Changes 🔧

• ref(types): add partial type hints for SamplingContext by NamitAdhikari in #5442

• ref: Remove references to unsupported attribute types by alexander-alderman-webb in #5425
• ci: Pin setuptools for linting and chalice tests by alexander-alderman-webb in #5438

---

_{🤖 This preview updates automatically when you update the PR.}

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

_ASGIScope marks optional ASGI fields as required

Medium Severity

The _ASGIScope TypedDict uses total=True (the default), marking all fields as required. Per the ASGI HTTP connection scope spec, server, client, scheme, raw_path, and state are optional. Developers relying on these type hints might access fields like scope["client"] or scope["server"] directly and hit KeyError at runtime when the ASGI server omits them. These fields need NotRequired wrapping.

 

[NamitAdhikari]

@cursoragent As per official ASGI Spec, I have made fields optional.

[cursor]

Unable to authenticate your request. Please make sure to connect your GitHub account to Cursor. Go to Cursor

[cursor]

Missing gcp_event field in _SamplingContextTyped TypedDict

Low Severity

The _SamplingContextTyped TypedDict includes gcp_env but is missing the gcp_event field. The GCP integration passes both "gcp_env" and "gcp_event" in the custom sampling context. This omission means developers using GCP Cloud Functions won't see gcp_event in autocomplete, despite it being available at runtime. The Union with dict[str, Any] prevents a type error, but the field is still undocumented in the typed definition.

 

[NamitAdhikari]

@cursoragent I have added gcp_event as well.

[cursor]

Unable to authenticate your request. Please make sure to connect your GitHub account to Cursor. Go to Cursor

[NamitAdhikari]

Looks like I need write permission in the main repo for the tests to pass. Someone please let me know, what I can do meanwhile.