Repository: litestar-org/litestar

Issue:
Docs: Document SSE
### Summary

The SSE documentation is currently lacking:

- Docs for `ServerSentEventMessage`
- Sending messages a dicts



<!-- POLAR PLEDGE BADGE START -->
---
> [!NOTE]  
> While we are open for sponsoring on [GitHub Sponsors](https://github.com/sponsors/litestar-org/) and 
> [OpenCollective](https://opencollective.com/litestar), we also utilize [Polar.sh](https://polar.sh/) to engage in pledge-based sponsorship.
>
> Check out all issues funded or available for funding [on our Polar.sh dashboard](https://polar.sh/litestar-org)
> * If you would like to see an issue prioritized, make a pledge towards it!
> * We receive the pledge once the issue is completed & verified
> * This, along with engagement in the community, helps us know which features are a priority to our users.

<a href="https://polar.sh/litestar-org/litestar/issues/3011">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://polar.sh/api/github/litestar-org/litestar/issues/3011/pledge.svg?darkmode=1">
  <img alt="Fund with Polar" src="https://polar.sh/api/github/litestar-org/litestar/issues/3011/pledge.svg">
</picture>
</a>
<!-- POLAR PLEDGE BADGE END -->



Discussion:
Any suggestions here @euri10?
ok just reading the current docs here:

https://docs.litestar.dev/latest/usage/responses.html#server-sent-event-responses

I think everything @provinzkraut mentions is currently in the docs:

ServerSentEventMessage is mentionned, the dict option as well

now I see room for improvment I'd say in the example given; it currently only yield a str and we "should" maybe yield a ServerSentEventMessage and show it that way with all the other possibilities we test,

if agree I can tweak the example, does that make sense to you >?

Resolving patch:
diff --git a/docs/examples/responses/sse_responses.py b/docs/examples/responses/sse_responses.py
--- a/docs/examples/responses/sse_responses.py
+++ b/docs/examples/responses/sse_responses.py
@@ -2,15 +2,28 @@
 from typing import AsyncGenerator
 
 from litestar import Litestar, get
-from litestar.response import ServerSentEvent
+from litestar.response import ServerSentEvent, ServerSentEventMessage
+from litestar.types import SSEData
 
 
-async def my_generator() -> AsyncGenerator[bytes, None]:
+async def my_generator() -> AsyncGenerator[SSEData, None]:
     count = 0
     while count < 10:
         await sleep(0.01)
         count += 1
+        # In the generator you can yield integers, strings, bytes, dictionaries, or ServerSentEventMessage objects
+        # dicts can have the following keys: data, event, id, retry, comment
+
+        # here we yield an integer
+        yield count
+        # here a string
         yield str(count)
+        # here bytes
+        yield str(count).encode("utf-8")
+        # here a dictionary
+        yield {"data": 2 * count, "event": "event2", "retry": 10}
+        # here a ServerSentEventMessage object
+        yield ServerSentEventMessage(event="something-with-comment", retry=1000, comment="some comment")
 
 
 @get(path="/count", sync_to_thread=False)


Test patch:
diff --git a/tests/examples/test_responses/test_sse_responses.py b/tests/examples/test_responses/test_sse_responses.py
--- a/tests/examples/test_responses/test_sse_responses.py
+++ b/tests/examples/test_responses/test_sse_responses.py
@@ -8,6 +8,4 @@ async def test_sse_responses_example() -> None:
     async with AsyncTestClient(app=app) as client:
         async with aconnect_sse(client, "GET", f"{client.base_url}/count") as event_source:
             events = [sse async for sse in event_source.aiter_sse()]
-            assert len(events) == 10
-        assert all(e.event == "message" for e in events)
-        assert all(e.data == str(i) for i, e in enumerate(events, 1))
+            assert len(events) == 50