align datastar_response behavior with docs (tests, fixes, examples)

[mmacpherson]

(PR statement heavily revised after initial submission; see comment below.)

Problem

@datastar_response returned a coroutine for sync handlers, so frameworks treated them as async and ran blocking work on the event loop. That stalls unrelated requests under load and produces “coroutine was never awaited” warnings if you call the decorated function directly.

Fix

Keep the wrapper sync and normalize the result: async iterable → DatastarResponse, sync iterable → DatastarResponse, awaitable → tiny async gen that awaits once → DatastarResponse, else wrap the value. Applied consistently across starlette/fastapi/fasthtml/litestar/django/sanic.

Sync handlers now stay in the threadpool; return shape is always DatastarResponse.

(sanic streams generators via request.respond; returns None there)

Tests

• Matrix unit tests for {sync, async} × {value, generator} across the adapters (Django async gen skipped).
• Integration tests (uvicorn + httpx) for Starlette/FastAPI/FastHTML/Litestar covering all four handler shapes; assert ping isn’t stalled by a blocking sync handler and SSE payload markers are present.
• Runtime/concurrency test for sync-callable behavior and threadpool vs event-loop.

Docs

README notes the decorator preserves sync semantics.

Verification

All tests are green, warnings are upstream deprecations (litestar/websockets/py3.14).

make test  # which runs uv run --dev pytest

[gazpachoking]

Thanks for this. Just want to verify what it's fixing first though, what were the cases that weren't working as expected?

[mmacpherson]

@gazpachoking (Thanks for maintaining this and) thanks for the question; I should have been clearer, and this prodded me to get more specific about the issue.

I had initially said the decorator ‘didn’t work as expected’, which was too broad; the narrower issue is it returned a coroutine for sync handlers, so blocking work ran on the event loop. I use fasthtml, and I think I experienced that as the decorator "not working", when it was more likely things bogging down for me under load because of the sync/async issue.

In this updated PR, I add some "matrix" tests, that establish that the decorator works/has worked for {sync, async} x {generator, not-generator} x {frameworks}. But I also add a test that shows the async/sync issue. Matrix tests pass under 0.7.0; the concurrency test fails under 0.7.0 and passes with this fix.

The third commit makes minor updates to the docs/egs.

I'm no expert in async/sync stuff, just a fasthtml + datastar user.

[gazpachoking]

Hmm. I see, I hadn't considered that but I guess transforming a sync handler into async could be surprising. Don't we have the opposite problem with this fix though, even async handlers will be turned into sync ones, thus causing a thread to be spawned?