Python SDK: Make response helpers opinionated about taking 0..N datastar events (#918)

* Make datastar opinionated about taking 0..N datastar events

* Remove old response class aliases

* Improve responses for sanic as well

* Update sanic example

* Switch quart to using DatastarResponse like the other frameworks

* Various cleanups

* Typing/linting from attribute generator merge

* Update response class documentation in the readme

* Declare the python sdk as typed

Author: gazpachoking

examples/python/django/ds/views.py

@@ -3,7 +3,7 @@
 from datetime import datetime
 
 from datastar_py.django import (
-    DatastarStreamingHttpResponse,
+    DatastarResponse,
     ServerSentEventGenerator,
     read_signals,
 )
@@ -65,7 +65,7 @@ async def time_updates():
             )
             await asyncio.sleep(1)
 
-    return DatastarStreamingHttpResponse(time_updates())
+    return DatastarResponse(time_updates())
 
 
 # WSGI Example
@@ -121,4 +121,4 @@ def time_updates():
             )
             time.sleep(0.5)
 
-    return DatastarStreamingHttpResponse(time_updates())
+    return DatastarResponse(time_updates())

examples/python/fastapi/app.py

@@ -13,7 +13,7 @@
 
 import uvicorn
 from datastar_py.fastapi import (
-    DatastarStreamingResponse,
+    DatastarResponse,
     ReadSignals,
     ServerSentEventGenerator,
 )
@@ -80,7 +80,7 @@ async def time_updates():
 async def updates(signals: ReadSignals):
     # ReadSignals is a dependency that automatically loads the signals from the request
     print(signals)
-    return DatastarStreamingResponse(time_updates())
+    return DatastarResponse(time_updates())
 
 
 if __name__ == "__main__":

examples/python/fasthtml/advanced.py

@@ -17,7 +17,7 @@
 from pathlib import Path
 
 import polars as pl
-from datastar_py.fasthtml import DatastarStreamingResponse, ServerSentEventGenerator
+from datastar_py.fasthtml import DatastarResponse, ServerSentEventGenerator
 from great_tables import GT
 from great_tables.data import reactions
 
@@ -94,10 +94,7 @@ def GreatTable(pattern=default_pattern):
 # rendered table into the DOM with the request's 'filter' value
 @app.post
 async def table(filter: str):
-    async def _():
-        yield ServerSentEventGenerator.merge_fragments(GreatTable(filter))
-
-    return DatastarStreamingResponse(_())
+    return DatastarResponse(ServerSentEventGenerator.merge_fragments(GreatTable(filter)))
 
 
 # Define default route which returns a FastTag from a GET request.
@@ -159,7 +156,7 @@ async def clock():
 
 @rt
 async def time():
-    return DatastarStreamingResponse(clock())
+    return DatastarResponse(clock())
 
 
 @rt
@@ -169,7 +166,7 @@ async def _():
         await asyncio.sleep(1)
         yield ServerSentEventGenerator.merge_fragments(HELLO_BUTTON)
 
-    return DatastarStreamingResponse(_())
+    return DatastarResponse(_())
 
 
 @rt
@@ -189,7 +186,7 @@ async def _():
         await asyncio.sleep(1)
         yield ServerSentEventGenerator.merge_fragments(reset_and_hello)
 
-    return DatastarStreamingResponse(_())
+    return DatastarResponse(_())
 
 
 # Define the button once so that it can be used in the index response

examples/python/fasthtml/simple.py

@@ -12,7 +12,7 @@
 from datetime import datetime
 from pathlib import Path
 
-from datastar_py.fasthtml import DatastarStreamingResponse, ServerSentEventGenerator, read_signals
+from datastar_py.fasthtml import DatastarResponse, ServerSentEventGenerator, read_signals
 
 # ruff: noqa: F403, F405
 from fasthtml.common import *
@@ -66,7 +66,7 @@ async def clock():
 async def updates(request):
     signals = await read_signals(request)
     print(signals)
-    return DatastarStreamingResponse(clock())
+    return DatastarResponse(clock())
 
 
 if __name__ == "__main__":

examples/python/litestar/app.py

@@ -12,7 +12,12 @@
 from datetime import datetime
 
 import uvicorn
-from datastar_py.litestar import DatastarSSE, ServerSentEventGenerator, read_signals
+from datastar_py.litestar import (
+    DatastarResponse,
+    ServerSentEventGenerator,
+    read_signals,
+)
+from datastar_py.sse import DatastarEvent
 
 from litestar import Litestar, MediaType, get
 from litestar.di import Provide
@@ -57,7 +62,7 @@ async def read_root() -> str:
     return HTML.replace("CURRENT_TIME", f"{datetime.isoformat(datetime.now())}")
 
 
-async def time_updates() -> AsyncGenerator[str, None]:
+async def time_updates() -> AsyncGenerator[DatastarEvent, None]:
     while True:
         yield ServerSentEventGenerator.merge_fragments(
             f"""<span id="currentTime">{datetime.now().isoformat()}"""
@@ -72,9 +77,9 @@ async def time_updates() -> AsyncGenerator[str, None]:
 # We aren't using the signals for anything meaningful here, but `read_signals` can be
 # used as a dependency to automatically parse the signals from the request.
 @get("/updates", dependencies={"signals": Provide(read_signals)})
-async def updates(signals: dict | None) -> DatastarSSE:
+async def updates(signals: dict | None) -> DatastarResponse:
     print(signals)
-    return DatastarSSE(time_updates())
+    return DatastarResponse(time_updates())
 
 
 app = Litestar(route_handlers=[read_root, updates])

examples/python/quart/app.py

@@ -11,8 +11,8 @@
 from datetime import datetime
 
 from datastar_py.quart import (
+    DatastarResponse,
     ServerSentEventGenerator,
-    make_datastar_response,
     read_signals,
 )
 
@@ -72,8 +72,7 @@ async def time_updates():
             )
             await asyncio.sleep(1)
 
-    response = await make_datastar_response(time_updates())
-    return response
+    return DatastarResponse(time_updates())
 
 
 @app.route("/")

examples/python/sanic/app.py

@@ -11,7 +11,12 @@
 from datetime import datetime
 
 from datastar_py.consts import FragmentMergeMode
-from datastar_py.sanic import ServerSentEventGenerator, datastar_respond, read_signals
+from datastar_py.sanic import (
+    DatastarResponse,
+    ServerSentEventGenerator,
+    datastar_respond,
+    read_signals,
+)
 
 from sanic import Sanic
 from sanic.response import html
@@ -62,9 +67,7 @@ async def hello_world(request):
 
 @app.get("/add_signal")
 async def add_signal(request):
-    response = await datastar_respond(request)
-
-    await response.send(
+    return DatastarResponse(
         ServerSentEventGenerator.merge_fragments(
             """
             <div class="time signal">
@@ -76,14 +79,10 @@ async def add_signal(request):
         )
     )
 
-    await response.eof()
-
 
 @app.get("/add_fragment")
 async def add_fragment(request):
-    response = await datastar_respond(request)
-
-    await response.send(
+    return DatastarResponse(
         ServerSentEventGenerator.merge_fragments(
             f"""\
             <div class="time fragment">
@@ -95,8 +94,6 @@ async def add_fragment(request):
         )
     )
 
-    await response.eof()
-
 
 @app.get("/updates")
 async def updates(request):

sdk/python/README.md

@@ -48,9 +48,38 @@ async def updates():
 
 ## Response Helpers
 
-The response for the quart example above could be rewritten using the helpers:
+A datastar response consists of 0..N datastar events. There are response
+classes included to make this easy in all of the supported frameworks.
+
+The following examples will work across all supported frameworks when the
+response class is imported from the appropriate framework package.
+e.g. `from datastar_py.quart import DatastarResponse` The containing functions
+are not shown here, as they will differ per framework.
+
+
 ```python
-    return await make_datastar_response(time_updates())
+# 0 events, a 204
+return DatastarResponse()
+# 1 event
+return DatastarResponse(ServerSentEventGenerator.merge_fragments("<div id='mydiv'></div>"))
+# 2 events
+return DatastarResponse([
+    ServerSentEventGenerator.merge_fragments("<div id='mydiv'></div>"),
+    ServerSentEventGenerator.merge_signals({"mysignal": "myval"}),
+])
+# N events, a long lived stream (for all frameworks but sanic)
+async def updates():
+    while True:
+        yield ServerSentEventGenerator.merge_fragments("<div id='mydiv'></div>")
+        await asyncio.sleep(1)
+return DatastarResponse(updates())
+# A long lived stream for sanic
+response = await datastar_respond(request)
+# which is just a helper for the following
+# response = await request.respond(DatastarResponse())
+while True:
+    await response.send(ServerSentEventGenerator.merge_fragments("<div id='mydiv'></div>"))
+    await asyncio.sleep(1)
 ```
 
 ## Signal Helpers

sdk/python/pyproject.toml

@@ -104,5 +104,9 @@ select = [
     "SIM",
     # isort
     "I",
+    # Annotations
+    "ANN",
+    # Ruff specific
+    "RUF",
 ]
-fixable = ["ALL"]
+fixable = ["ALL"]

sdk/python/src/datastar_py/__init__.py

@@ -4,14 +4,14 @@
 from collections.abc import Mapping
 from typing import Any
 
-from .sse import SSE_HEADERS, ServerSentEventGenerator
 from .attributes import attribute_generator
+from .sse import SSE_HEADERS, ServerSentEventGenerator
 
-__all__ = ["attribute_generator", "ServerSentEventGenerator", "SSE_HEADERS"]
+__all__ = ["SSE_HEADERS", "ServerSentEventGenerator", "attribute_generator"]
 
 
 def _read_signals(
-    method: str, headers: Mapping, params: Mapping, body: str | bytes
+    method: str, headers: Mapping[str, str], params: Mapping, body: str | bytes
 ) -> dict[str, Any] | None:
     if "Datastar-Request" not in headers:
         return None