Make datastar opinionated about taking 0..N datastar events

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,11 @@
 from datetime import datetime
 
 import uvicorn
-from datastar_py.litestar import DatastarSSE, ServerSentEventGenerator, read_signals
+from datastar_py.litestar import (
+    ServerSentEventGenerator,
+    read_signals,
+    DatastarResponse,
+)
 
 from litestar import Litestar, MediaType, get
 from litestar.di import Provide
@@ -72,9 +76,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])

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

@@ -6,11 +6,11 @@
 
 from .sse import SSE_HEADERS, ServerSentEventGenerator
 
-__all__ = ["ServerSentEventGenerator", "SSE_HEADERS"]
+__all__ = ["SSE_HEADERS", "ServerSentEventGenerator"]
 
 
 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

sdk/python/src/datastar_py/django.py

@@ -1,27 +1,49 @@
 from __future__ import annotations
 
-from functools import wraps
-from typing import Any
+from typing import TYPE_CHECKING, Any
+from warnings import deprecated
 
 from django.http import HttpRequest
 from django.http import StreamingHttpResponse as _StreamingHttpResponse
 
 from . import _read_signals
-from .sse import SSE_HEADERS, ServerSentEventGenerator
+from .sse import SSE_HEADERS, DatastarEvent, DatastarEvents, ServerSentEventGenerator
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
 
 __all__ = [
     "SSE_HEADERS",
+    "DatastarResponse",
     "DatastarStreamingHttpResponse",
     "ServerSentEventGenerator",
     "read_signals",
 ]
 
 
-class DatastarStreamingHttpResponse(_StreamingHttpResponse):
-    @wraps(_StreamingHttpResponse.__init__)
-    def __init__(self, *args, **kwargs):
-        kwargs["headers"] = {**SSE_HEADERS, **kwargs.get("headers", {})}
-        super().__init__(*args, **kwargs)
+class DatastarResponse(_StreamingHttpResponse):
+    """Respond with 0..N `DatastarEvent`s"""
+
+    def __init__(
+        self,
+        content: DatastarEvents = None,
+        *,
+        status: int | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        if not content:
+            super().__init__(tuple(), status=status or 204, headers=headers)
+            return
+        headers = {**SSE_HEADERS, **(headers or {})}
+        if isinstance(content, DatastarEvent):
+            content = (content,)
+        super().__init__(content, status=status, headers=headers)
+
+
+@deprecated("Use DatastarResponse instead")
+class DatastarStreamingHttpResponse(DatastarResponse):
+    pass
 
 
 def read_signals(request: HttpRequest) -> dict[str, Any] | None:

sdk/python/src/datastar_py/fastapi.py

@@ -3,14 +3,15 @@
 from fastapi import Depends
 
 from .sse import SSE_HEADERS, ServerSentEventGenerator
-from .starlette import DatastarStreamingResponse, read_signals
+from .starlette import DatastarResponse, DatastarStreamingResponse, read_signals
 
 __all__ = [
     "SSE_HEADERS",
-    "ServerSentEventGenerator",
+    "DatastarResponse",
+    "DatastarStreamingResponse",
     "ReadSignals",
+    "ServerSentEventGenerator",
     "read_signals",
-    "DatastarStreamingResponse",
 ]
 
 

sdk/python/src/datastar_py/fasthtml.py

@@ -1,8 +1,9 @@
 from .sse import SSE_HEADERS, ServerSentEventGenerator
-from .starlette import DatastarStreamingResponse, read_signals
+from .starlette import DatastarResponse, DatastarStreamingResponse, read_signals
 
 __all__ = [
     "SSE_HEADERS",
+    "DatastarResponse",
     "DatastarStreamingResponse",
     "ServerSentEventGenerator",
     "read_signals",