Clarify decorator streaming behavior in docs

mmacpherson · mmacpherson · commit c1e0d122fb88 · 2025-11-22T15:05:54.000-08:00
diff --git a/README.md b/README.md
@@ -135,11 +135,15 @@ async def updates(request):
 ### Response Decorator
 To make returning a `DatastarResponse` simpler, there is a decorator
 `datastar_response` available that automatically wraps a function result in
-`DatastarResponse`. It works on async and regular functions and generator
-functions. The main use case is when using a generator function, as you can
-avoid a second generator function inside your response function. The decorator
-works the same for any of the supported frameworks, and should be used under
-any routing decorator from the framework.
+`DatastarResponse`. The decorator inspects what your function returns:
+
+- async generators/iterables (`__aiter__`) and sync generators/iterables (`__iter__`) are streamed
+- awaitables (coroutines/tasks) are awaited and their single result is streamed once
+- everything else is wrapped as-is
+
+That means you can write a generator route handler without adding an extra
+wrapper generator. Apply `@datastar_response` under your framework's route
+decorator.
 
 ```python
 # Import the decorator from the package specific to your framework
@@ -153,6 +157,20 @@ async def my_route(request):
         await asyncio.sleep(1)
 ```
 
+You can also return a single event from an async function and it will be awaited
+and streamed once:
+
+```python
+@app.get("/single")
+@datastar_response
+async def single_event(request):
+    return SSE.patch_signals({"done": True})
+```
+
+Note: the Quart and Django adapters keep the wrapper async (as the frameworks expect),
+so when calling a decorated view directly you must still `await` it. The other adapters
+return a `DatastarResponse` immediately.
+
 ## Signal Helpers
 The current state of the datastar signals is included by default in every
 datastar request. A helper is included to load those signals for each
diff --git a/examples/fastapi/app_with_decorator.py b/examples/fastapi/app_with_decorator.py
@@ -0,0 +1,48 @@
+# /// script
+# dependencies = ["datastar-py", "fastapi", "uvicorn"]
+# ///
+import asyncio
+from datetime import datetime
+
+from datastar_py.fastapi import datastar_response
+from datastar_py.sse import ServerSentEventGenerator as SSE
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+
+app = FastAPI()
+
+
+@app.get("/", response_class=HTMLResponse)
+async def index():
+    return """
+    <!DOCTYPE html>
+    <html>
+        <head>
+            <title>Datastar.py FastAPI Decorator Example</title>
+            <script type="module" src="https://cdn.jsdelivr.net/gh/starfederation/datastar@v1.0.0-RC.6/bundles/datastar.js"></script>
+        </head>
+        <body >
+            <h1>Datastar.py FastAPI Decorator Example</h1>
+            <div id="time-div" data-init="@get('/updates')"></div>
+        </body>
+    </html>
+    """
+
+
+@app.get("/updates")
+@datastar_response
+async def updates():
+    """
+    This async generator yields a new time every second. The @datastar_response
+    decorator handles wrapping the yielded events in a DatastarResponse.
+    """
+    while True:
+        now = datetime.now().isoformat()
+        yield SSE.patch_elements(f'<div id="time-div">Current Time: {now}</div>')
+        await asyncio.sleep(1)
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
diff --git a/examples/fasthtml/decorator.py b/examples/fasthtml/decorator.py
@@ -0,0 +1,53 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["datastar-py", "python-fasthtml"]
+# [tool.uv.sources]
+# datastar-py = { path = "../../" }
+# ///
+import asyncio
+from datetime import datetime
+
+# ruff: noqa: F403, F405
+from fasthtml.common import *
+
+from datastar_py.fasthtml import datastar_response
+from datastar_py.sse import ServerSentEventGenerator as SSE
+
+app, rt = fast_app(
+    htmx=False,
+    hdrs=(
+        Script(
+            type="module",
+            src="https://cdn.jsdelivr.net/gh/starfederation/datastar@v1.0.0-RC.6/bundles/datastar.js",
+        ),
+    ),
+)
+
+
+@rt("/")
+def index():
+    return Titled(
+        "Datastar.py FastHTML Decorator Example",
+        Body(
+            Div(cls="wrapper")(
+                Div(id="time-div", data_init="@get('/updates')"),
+            )
+        ),
+    )
+
+
+@rt("/updates")
+@datastar_response
+async def updates():
+    """
+    Async generator that streams a new timestamp every second.
+    The @datastar_response decorator wraps the generator in a DatastarResponse.
+    """
+    while True:
+        now = datetime.now().isoformat()
+        yield SSE.patch_elements(Div(id="time-div")(f"Current Time: {now}"))
+        await asyncio.sleep(1)
+
+
+if __name__ == "__main__":
+    serve()
