Skip to content

docs: correct the Python and Go event data model tip - #2160

Merged
SteveSandersonMS merged 2 commits into
mainfrom
sdk-bugfix-68
Jul 30, 2026
Merged

docs: correct the Python and Go event data model tip#2160
SteveSandersonMS merged 2 commits into
mainfrom
sdk-bugfix-68

Conversation

@examon

@examon examon commented Jul 30, 2026

Copy link
Copy Markdown
Contributor

What

docs/features/streaming-events.md told Python and Go users that session event payloads use a single Data class/struct with every field optional, and that fields not populated for an event come back as None/nil. Both bindings use a separate data type per event, so neither behaves that way.

Fixes #2159

Why the old text was wrong

Go. event.Data is the SessionEventData interface (go/rpc/zsession_events.go), which carries no data fields, so reading one off it does not compile:

./main.go:41:35: event.Data.ToolName undefined (type rpc.SessionEventData has no field or method ToolName)

toolName is listed in the doc's own tool.execution_start table, so this is a field the tip said was readable for that event.

Python. event.data is a per-event dataclass, so reading a field that belongs to a different event raises instead of returning None:

AttributeError: 'ToolExecutionStartData' object has no attribute 'delta_content'

The class named Data still exists in the Python binding, but it is a shim for manually constructed payloads with no declared fields; event delivery never produces it, and unrecognized events fall back to RawSessionEventData.

The tip was accurate when it was written. Go moved to per-event data structs in #1037 and Python in #1063. The Go change updated this file's Go example and left the prose behind. Docs validation extracts and compiles fenced code blocks only, so nothing checks prose, which is why this file's own Go example uses event.Data.(*copilot.AssistantMessageDeltaData) about sixty lines above a tip saying that is unnecessary.

What changed

  • docs/features/streaming-events.md - the Python/Go tip now describes per-event data types, using the wording the file already uses for the .NET tip directly below it.
  • .github/instructions/docs-style.instructions.md - the same sentence is used there as the example of a language-qualified callout, so it carried the same incorrect claim.

Prose only. No code, generated files, codegen templates, schemas, samples or tests.

Verification

  • Programs written to follow the corrected tip compile and run in both Go and Python against a build of this branch. Programs written to follow the old tip still fail with the errors above.
  • npm run validate:go (48/48) and npm run validate:py (57/57) pass, and the extracted code corpus is byte-identical to main since only prose changed.
  • The corrected tip renders as a Tip callout.

Not included

Java uses per-event classes and Rust exposes the payload as untyped JSON. Neither has a tip in this section today and this change does not add one.

The Python/Go tip in the streaming events reference described a single
`Data` class/struct with every field optional, where fields that are not
populated for an event come back as `None`/`nil`. Both bindings use a
separate data type per event, so code written against that tip does not
work: in Go `event.Data` is the `SessionEventData` interface and reading a
field off it does not compile, and in Python `event.data` is a per-event
dataclass, so reading a field that belongs to another event raises
`AttributeError` instead of returning `None`.

The tip was accurate when it was added and went stale when both bindings
moved to per-event data types. Describe the per-event model instead, using
the wording the same file already uses for .NET, and correct the copy of
the same sentence that the docs style guide uses as its example of a
language-qualified callout.
Copilot AI review requested due to automatic review settings July 30, 2026 10:48
@examon
examon requested a review from a team as a code owner July 30, 2026 10:48

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Corrects Python and Go streaming-event documentation to reflect their per-event payload types.

Changes:

  • Updates the streaming-events tip.
  • Aligns the docs style-guide example.
Show a summary per file
File Description
docs/features/streaming-events.md Corrects the Python and Go event data model guidance.
.github/instructions/docs-style.instructions.md Updates the language-qualified callout example.

Review details

  • Files reviewed: 2/2 changed files
  • Comments generated: 1
  • Review effort level: Medium

Comment thread docs/features/streaming-events.md Outdated
Copilot AI review requested due to automatic review settings July 30, 2026 10:55

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review details

  • Files reviewed: 2/2 changed files
  • Comments generated: 0 new
  • Review effort level: Medium

@SteveSandersonMS
SteveSandersonMS merged commit ad67361 into main Jul 30, 2026
30 checks passed
@SteveSandersonMS
SteveSandersonMS deleted the sdk-bugfix-68 branch July 30, 2026 12:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: streaming events tip describes a single Data class for Python and Go, but both use per-event data types

3 participants