Skip to content

Feature: Strongly type Python events #1016

@Techbert08

Description

@Techbert08

Hi,

I was trying to build against the SDK in Python, and I got confused about which events carried what payloads. The Data class is a union of all possible data fields:

SessionEvent largely a pair of enum and Data with a long docstring:

Other bindings in dotnet, for example, strongly type the events, so you know what events carry what payloads:

public partial class SessionStartEvent : SessionEvent

I think stronger type hinting on the Python side would help make the SDK easier to consume by catching classes of bugs at IDE/Pyright/agent coding time. It has precedent on the Claude Agent SDK, which does adopt this pattern for its message type:

https://github.com/anthropics/claude-agent-sdk-python/blob/13f65c81e2bec2a5d1f1e1efdd45aa061c4ec43f/src/claude_agent_sdk/types.py#L1071

It's a breaking change to people using type hints, but I suspect we could do it in such a way that the only breaks would be people genuinely looking in the wrong place for payloads (i.e. silent bugs).

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions