G2: F22 — add Event.is_error() helper and document .type-check contract

Why: wait_for_event matches a single EventType; when callers pass
[X, ERROR] to send() or wait_for_events, the return value may be an
error response whose payload is {"reason": "..."} — not the command-
specific keys the caller expects.  Without a documented contract and
a convenience helper, every call site independently forgets to check
.type before accessing payload keys, leading to KeyError (F21/M01,
M04) or silent fallthrough.  The is_error() helper and docstrings on
send()/wait_for_events() establish the contract that subsequent
commits in this branch rely on.

Refs: Forensics report finding F22
This commit is contained in:
Matthew Wolter
2026-04-11 20:03:39 -07:00
parent fbf84cbdac
commit 6a74f07da7
2 changed files with 28 additions and 4 deletions

View File

@@ -104,6 +104,17 @@ class Event:
if kwargs:
self.attributes.update(kwargs)
def is_error(self) -> bool:
"""Return True if this event represents an error response.
Callers that include ``EventType.ERROR`` in their expected-events
list **must** check ``result.is_error()`` (or ``result.type ==
EventType.ERROR``) before accessing keyed payload fields, because
an ERROR payload contains ``{"reason": "..."}`` — not the
command-specific keys the caller expects on the happy path.
"""
return self.type == EventType.ERROR
def clone(self):
"""
Create a copy of the event.