async iteration support

conftest.py

@@ -1,5 +1,10 @@
+import asyncio
+import typing as t
+
 import pytest
 
+from htpy import Node, aiter_node, iter_node
+
 
 @pytest.fixture(scope="session")
 def django_env() -> None:
@@ -13,3 +18,23 @@ def django_env() -> None:
         ]
     )
     django.setup()
+
+
+@pytest.fixture(params=["sync", "async"])
+def to_list(request: pytest.FixtureRequest) -> t.Any:
+    def func(node: Node) -> t.Any:
+        if request.param == "sync":
+            return list(iter_node(node))
+        else:
+
+            async def get_list() -> t.Any:
+                return [chunk async for chunk in aiter_node(node)]
+
+            return asyncio.run(get_list(), debug=True)
+
+    return func
+
+
+@pytest.fixture
+def to_str(to_list: t.Any) -> t.Any:
+    return lambda node: "".join(to_list(node))

docs/streaming.md

@@ -1,7 +1,7 @@
 # Streaming of Contents
 
 Internally, htpy is built with generators. Most of the time, you would render
-the full page with `str()`, but htpy can also incrementally generate pages which
+the full page with `str()`, but htpy can also incrementally generate pages synchronously or asynchronous which
 can then be streamed to the browser. If your page uses a database or other
 services to retrieve data, you can sending the first part of the page to the
 client while the page is being generated.
@@ -16,7 +16,6 @@ client while the page is being generated.
 
 This video shows what it looks like in the browser to generate a HTML table with [Django StreamingHttpResponse](https://docs.djangoproject.com/en/5.0/ref/request-response/#django.http.StreamingHttpResponse) ([source code](https://github.com/pelme/htpy/blob/main/examples/djangoproject/stream/views.py)):
 <video width="500" controls loop >
-
   <source src="/assets/stream.webm" type="video/webm">
 </video>
 
@@ -111,3 +110,59 @@ print(
 # output: <div><h1>Fibonacci!</h1>fib(12)=6765</div>
 
 ```
+
+
+## Asynchronous streaming
+
+It is also possible to use htpy to stream fully asynchronous. This intended to be used
+with ASGI/async web frameworks/servers such as Starlette and Django. You can
+build htpy components using Python's `asyncio` module and the `async`/`await`
+syntax.
+
+### Starlette, ASGI and uvicorn example
+
+```python
+title="starlette_demo.py"
+import asyncio
+from collections.abc import AsyncIterator
+
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import StreamingResponse
+
+from htpy import Element, div, h1, li, p, ul
+
+app = Starlette(debug=True)
+
+
+@app.route("/")
+async def index(request: Request) -> StreamingResponse:
+    return StreamingResponse(await index_page(), media_type="text/html")
+
+
+async def index_page() -> Element:
+    return div[
+        h1["Starlette Async example"],
+        p["This page is generated asynchronously using Starlette and ASGI."],
+        ul[(li[str(num)] async for num in slow_numbers(1, 10))],
+    ]
+
+
+async def slow_numbers(minimum: int, maximum: int) -> AsyncIterator[int]:
+    for number in range(minimum, maximum + 1):
+        yield number
+        await asyncio.sleep(0.5)
+
+```
+
+Run with [uvicorn](https://www.uvicorn.org/):
+
+
+```
+$ uvicorn starlette_demo:app
+```
+
+In the browser, it looks like this:
+<video width="500" controls loop >
+  <source src="/assets/starlette.webm" type="video/webm">
+</video>

examples/async_coroutine.py

@@ -0,0 +1,24 @@
+import asyncio
+import random
+
+from htpy import Element, b, div, h1
+
+
+async def magic_number() -> Element:
+    await asyncio.sleep(1)
+    return b[f"The Magic Number is: {random.randint(1, 100)}"]
+
+
+async def my_component() -> Element:
+    return div[
+        h1["The Magic Number"],
+        await magic_number(),
+    ]
+
+
+async def main() -> None:
+    async for _chunk in my_component():
+        print("got: chunk")
+
+
+asyncio.run(main())

examples/starlette_app.py

@@ -0,0 +1,29 @@
+import asyncio
+from collections.abc import AsyncIterator
+
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import StreamingResponse
+
+from htpy import Element, div, h1, li, p, ul
+
+app = Starlette(debug=True)
+
+
+@app.route("/")
+async def index(request: Request) -> StreamingResponse:
+    return StreamingResponse(await index_page(), media_type="text/html")
+
+
+async def index_page() -> Element:
+    return div[
+        h1["Starlette Async example"],
+        p["This page is generated asynchronously using Starlette and ASGI."],
+        ul[(li[str(num)] async for num in slow_numbers(1, 10))],
+    ]
+
+
+async def slow_numbers(minimum: int, maximum: int) -> AsyncIterator[int]:
+    for number in range(minimum, maximum + 1):
+        yield number
+        await asyncio.sleep(0.5)

htpy/__init__.py

@@ -6,7 +6,14 @@
 import dataclasses
 import functools
 import typing as t
-from collections.abc import Callable, Iterable, Iterator
+from collections.abc import (
+    AsyncIterable,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Iterable,
+    Iterator,
+)
 
 from markupsafe import Markup as _Markup
 from markupsafe import escape as _escape
@@ -191,10 +198,73 @@ def _iter_node_context(x: Node, context_dict: dict[Context[t.Any], t.Any]) -> It
     elif isinstance(x, Iterable):  # pyright: ignore [reportUnnecessaryIsInstance]
         for child in x:
             yield from _iter_node_context(child, context_dict)
+    elif isinstance(x, Awaitable | AsyncIterable):  # pyright: ignore[reportUnnecessaryIsInstance]
+        raise ValueError(
+            f"{x!r} is not a valid child element. "
+            "Use async iteration to retrieve element content: https://htpy.dev/async/"
+        )
     else:
         raise ValueError(f"{x!r} is not a valid child element")
 
 
+def aiter_node(x: Node) -> AsyncIterator[str]:
+    return _aiter_node_context(x, {})
+
+
+async def _aiter_node_context(
+    x: Node, context_dict: dict[Context[t.Any], t.Any]
+) -> AsyncIterator[str]:
+    while True:
+        if isinstance(x, Awaitable):
+            x = await x
+            continue
+
+        if not isinstance(x, BaseElement) and callable(x):
+            x = x()
+            continue
+
+        break
+
+    if x is None:
+        return
+
+    if x is True:
+        return
+
+    if x is False:
+        return
+
+    if isinstance(x, BaseElement):
+        async for child in x._aiter_context(context_dict):  # pyright: ignore [reportPrivateUsage]
+            yield child
+    elif isinstance(x, ContextProvider):
+        async for chunk in _aiter_node_context(x.func(), {**context_dict, x.context: x.value}):  # pyright: ignore [reportUnknownMemberType]
+            yield chunk
+
+    elif isinstance(x, ContextConsumer):
+        context_value = context_dict.get(x.context, x.context.default)
+        if context_value is _NO_DEFAULT:
+            raise LookupError(
+                f'Context value for "{x.context.name}" does not exist, '
+                f"requested by {x.debug_name}()."
+            )
+        async for chunk in _aiter_node_context(x.func(context_value), context_dict):
+            yield chunk
+
+    elif isinstance(x, str | _HasHtml):
+        yield str(_escape(x))
+    elif isinstance(x, Iterable):
+        for child in x:  # type: ignore[assignment]
+            async for chunk in _aiter_node_context(child, context_dict):
+                yield chunk
+    elif isinstance(x, AsyncIterable):  # pyright: ignore[reportUnnecessaryIsInstance]
+        async for child in x:  # type: ignore[assignment]
+            async for chunk in _aiter_node_context(child, context_dict):  # pyright: ignore[reportUnknownArgumentType]
+                yield chunk
+    else:
+        raise ValueError(f"{x!r} is not a valid async child element")
+
+
 @functools.lru_cache(maxsize=300)
 def _get_element(name: str) -> Element:
     if not name.islower():
@@ -262,6 +332,15 @@ def __call__(self: BaseElementSelf, *args: t.Any, **kwargs: t.Any) -> BaseElemen
             self._children,
         )
 
+    async def _aiter_context(self, context: dict[Context[t.Any], t.Any]) -> AsyncIterator[str]:
+        yield f"<{self._name}{_attrs_string(self._attrs)}>"
+        async for x in _aiter_node_context(self._children, context):
+            yield x
+        yield f"</{self._name}>"
+
+    def __aiter__(self) -> AsyncIterator[str]:
+        return self._aiter_context({})
+
     def __iter__(self) -> Iterator[str]:
         return self._iter_context({})
 
@@ -296,8 +375,16 @@ def _iter_context(self, ctx: dict[Context[t.Any], t.Any]) -> Iterator[str]:
         yield "<!doctype html>"
         yield from super()._iter_context(ctx)
 
+    async def _aiter_context(self, context: dict[Context[t.Any], t.Any]) -> AsyncIterator[str]:
+        yield "<!doctype html>"
+        async for x in super()._aiter_context(context):
+            yield x
+
 
 class VoidElement(BaseElement):
+    async def _aiter_context(self, context: dict[Context[t.Any], t.Any]) -> AsyncIterator[str]:
+        yield f"<{self._name}{_attrs_string(self._attrs)}>"
+
     def _iter_context(self, ctx: dict[Context[t.Any], t.Any]) -> Iterator[str]:
         yield f"<{self._name}{_attrs_string(self._attrs)}>"
 
@@ -328,6 +415,8 @@ def __html__(self) -> str: ...
     | Callable[[], "Node"]
     | ContextProvider[t.Any]
     | ContextConsumer[t.Any]
+    | AsyncIterable["Node"]
+    | Awaitable["Node"]
 )
 
 Attribute: t.TypeAlias = None | bool | str | _HasHtml | _ClassNames

pyproject.toml

@@ -26,6 +26,7 @@ optional-dependencies.dev = [
     "mypy",
     "pyright",
     "pytest",
+    "pytest-asyncio",
     "black",
     "ruff",
     "django",

tests/test_async.py

@@ -0,0 +1,48 @@
+from collections.abc import AsyncIterator
+
+import pytest
+
+from htpy import Element, li, ul
+
+
+async def async_lis() -> AsyncIterator[Element]:
+    yield li["a"]
+    yield li["b"]
+
+
+async def hi() -> Element:
+    return li["hi"]
+
+
+@pytest.mark.asyncio
+async def test_async_iterator() -> None:
+    result = [chunk async for chunk in ul[async_lis()]]
+    assert result == ["<ul>", "<li>", "a", "</li>", "<li>", "b", "</li>", "</ul>"]
+
+
+@pytest.mark.asyncio
+async def test_cororoutinefunction_children() -> None:
+    result = [chunk async for chunk in ul[hi]]
+    assert result == ["<ul>", "<li>", "hi", "</li>", "</ul>"]
+
+
+@pytest.mark.asyncio
+async def test_cororoutine_children() -> None:
+    result = [chunk async for chunk in ul[hi()]]
+    assert result == ["<ul>", "<li>", "hi", "</li>", "</ul>"]
+
+
+def test_sync_iteration_with_async_children() -> None:
+    with pytest.raises(
+        ValueError,
+        match=(
+            r"<async_generator object async_lis at .+> is not a valid child element\. "
+            r"Use async iteration to retrieve element content: https://htpy.dev/async/"
+        ),
+    ):
+        str(ul[async_lis()])
+
+
+@pytest.mark.xfail
+def test_repr_with_async_children() -> None:
+    assert repr(ul[async_lis()]) == "<Element '<ul></ul>'>"