Async/starlette docs.

Author: pelme

docs/README.md

@@ -61,6 +61,8 @@ from a Python backend.
 
 - **Works with existing Python web framework:** Works great with Django, Flask or any other Python web framework!
 
+- **Full async support**: Render HTML fully async with ASGI frameworks such as Starlette and FastAPI.
+
 - **Works great with htmx:** htpy makes for a great experience when writing server rendered partials/components.
 
 - **Create reusable components:** Define components, snippets, complex layouts/pages as regular Python variables or functions.

docs/async.md

@@ -0,0 +1,83 @@
+# Async rendering
+
+htpy fully supports rendering HTML asynchronously. Combined with a async framework such as [Starlette/FastAPI](starlette.md), the entire web request can be processed async and the HTML page can be sent to the client incrementally as soon as it is ready.
+
+# Async components
+
+In addition to regular, [synchronous components](common-patterns.md), components can be defined as an `async def` coroutine. When rendering, htpy will `await` all async components:
+
+```py
+from htpy import li
+import asyncio
+
+async def get_text() -> str:
+    return "hi!"
+
+async def my_text() -> Renderable:
+    results = await get_text()
+    return p[results]
+```
+
+## Async iterators
+
+htpy will consume async iterators:
+
+```py
+from htpy import ul, li
+
+async def my_items() -> AsyncIterator[Renderable]:
+    yield li["a"]
+    yield li["b"]
+
+def my_list() -> Renderable:
+    return ul[my_items()]
+```
+
+# Rendering async content
+
+To retrieve results from async rendering, use the `aiter_chunks()` method. It returns an async iterator that yields the HTML document as bytes.
+
+```py
+import asyncio
+
+from htpy import p
+
+my_paragraph = p["hello!"]
+
+
+async def main() -> None:
+    async for chunk in my_paragraph.aiter_chunks():
+        print(chunk)
+
+
+asyncio.run(main())
+
+# output:
+# <p>
+# hello!
+# </p>
+```
+
+The async iterator returned by `aiter_chunks()` can be passed to your web framework's streaming response class. See the [htpy Starlette docs](starlette.md) for more information how to integrate with Starlette.
+
+!!! warning
+
+    Trying to get the string value of an async renderable like `str(element)` will result an exception:
+
+    ```py
+    Traceback (most recent call last):
+
+      File "/Users/andreas/code/htpy/examples/async_in_sync_context.py", line 7, in <module>
+        str(div[my_async_component()])
+        ~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    TypeError: <coroutine object my_async_component at 0x103471010> is not a valid child element.
+               Use the `.aiter_chunks()` method to retrieve the content: https://htpy.dev/async/
+    ```
+
+    Instead, use `aiter_chunks()`:
+
+    ```py
+    async for chunk in div[my_async_component()].aiter_chunks():
+        print(chunk)
+    ```

docs/starlette.md

@@ -1,21 +1,31 @@
-# Usage with Starlette
+# Usage with Starlette/FastAPI
 
 htpy can be used with Starlette to generate HTML. Since FastAPI is built upon Starlette, htpy can also be used with FastAPI.
 
-To return HTML contents, pass a htpy element to Starlette's `HTMLResponse`:
+htpy supports full async rendering of all components. See [async rendering](async.md) for more information.
+
+To return HTML contents, use the `HtpyResponse` class:
 
 ```py
 from starlette.applications import Starlette
 from starlette.requests import Request
-from starlette.responses import HTMLResponse
 from starlette.routing import Route
 
-from htpy import h1
+from htpy import Element, h1
+from htpy.starlette import HtpyResponse
+
+
+async def index_component() -> Element:
+    return h1["Hi Starlette!"]
 
 
-async def index(request: Request) -> HTMLResponse:
-    return HTMLResponse(h1["Hi Starlette!"])
+async def index(request: Request) -> HtpyResponse:
+    return HtpyResponse(index_component())
 
 
-app = Starlette(routes=[Route("/", index)])
+app = Starlette(
+    routes=[
+        Route("/", index),
+    ]
+)
 ```

examples/aiter_chunks.py

@@ -0,0 +1,13 @@
+import asyncio
+
+from htpy import p
+
+my_paragraph = p["hello!"]
+
+
+async def main():
+    async for chunk in my_paragraph.aiter_chunks():
+        print(chunk)
+
+
+asyncio.run(main())

examples/async_in_sync_context.py

@@ -0,0 +1,7 @@
+from htpy import div
+
+
+async def my_async_component(): ...
+
+
+str(div[my_async_component()])

examples/async_iterators.py

@@ -0,0 +1,25 @@
+from collections.abc import AsyncIterator
+
+from htpy import Element, li, ul
+
+
+async def my_items() -> AsyncIterator[Element]:
+    yield li["a"]
+    yield li["b"]
+
+
+def my_list() -> Element:
+    return ul[my_items()]
+
+
+import asyncio  # noqa: E402
+
+print(my_list())
+
+
+async def main():
+    async for chunk in my_list().aiter_chunks():
+        print(chunk)
+
+
+asyncio.run(main())

examples/starlette_hello_world.py

@@ -0,0 +1,21 @@
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.routing import Route
+
+from htpy import Renderable, h1
+from htpy.starlette import HtpyResponse
+
+
+async def index_component() -> Renderable:
+    return h1["Hi Starlette!"]
+
+
+async def index(request: Request) -> HtpyResponse:
+    return HtpyResponse(index_component())
+
+
+app = Starlette(
+    routes=[
+        Route("/", index),
+    ]
+)

mkdocs.yml

@@ -15,6 +15,7 @@ nav:
   - common-patterns.md
   - static-typing.md
   - django.md
+  - async.md
   - starlette.md
   - streaming.md
   - html2htpy.md