[saa-py] on_* decorator registration semantics (single-slot vs fan-out) are not documented

[musadiq1707]

Package

@attenlabs/saa-js

Version

0.1.0

What happened?

Bug / DX: saa-py documents @client.on_prediction decorator but on_* naming is ambiguous with direct assignment

Summary

The Python SDK README shows event registration exclusively via decorators:

@client.on_prediction
def _(event):
    ...

But it does not document whether the same method can also be used as a direct callable assignment (i.e. client.on_prediction = my_handler), which is a common pattern developers try first. It also does not document whether multiple handlers per event are supported.

This creates two real failure modes seen in community code:

1. A developer assigns client.on_turn_ready = handler (direct assignment) — the callback silently does nothing if on_turn_ready is a property that only supports decorator mode.
2. A developer registers two @client.on_turn_ready handlers expecting both to fire — only the last one does (or neither, if the second registration silently replaces the first).

Expected behaviour

The README should clearly document:

• Whether direct callable assignment is supported (or not).
• Whether multiple handlers per event are supported.
• If not, what happens when you register a second handler (replace? raise? no-op?).

Suggested fix

Add a "registering handlers" note under the Events section in packages/saa-py/README.md, e.g.:

Each on_* method is a single-slot decorator. Calling it a second time replaces the previous handler. For fan-out, wrap multiple calls in a single handler.

Labels

documentation, dx, saa-py

Steps to reproduce

Steps to reproduce

from saa import AttentionClient

client = AttentionClient(token="...")

# Pattern A: direct assignment — does this work?
client.on_turn_ready = lambda turn: print(turn.duration_sec)

# Pattern B: multiple decorators — do both fire?
@client.on_turn_ready
def handler_a(turn):
    print("handler A")

@client.on_turn_ready
def handler_b(turn):
    print("handler B")

client.start()

Environment

No response

Logs / errors