Add a consistent rendering protocol.

This change provides a consistent API to render a htpy object as HTML or
iterate over it.

This commit introduces stream_chunks() which is identical with
__iter__() but with a better name.

With the introduction of Fragment, this commit makes render_node and
iter_node redundant and they will be deprecated in another commit.

This commit removes all internal usages of render_node and iter_node so
they can be deprecated.

More info: #86 (comment)

Author: pelme

docs/usage.md

@@ -378,14 +378,14 @@ snippets as attributes:
 
 ```
 
-## Iterating of the Output
+## Streaming chunks
 
-Iterating over a htpy element will yield the resulting contents in chunks as
-they are rendered:
+htpy objects provide the `stream_chunks()` method to render an element with its
+children one piece at a time.
 
 ```pycon
 >>> from htpy import ul, li
->>> for chunk in ul[li["a"], li["b"]]:
+>>> for chunk in ul[li["a"], li["b"]].stream_chunks():
 ...     print(f"got a chunk: {chunk!r}")
 ...
 got a chunk: '<ul>'
@@ -399,13 +399,11 @@ got a chunk: '</ul>'
 
 ```
 
-Just like [render_node()](#render-elements-without-a-parent-orphans), there is
-`iter_node()` that can be used when you need to iterate over a list of elements
-without a parent:
+If you need to get the chunks of an element without parents, wrap it in a `Fragment`:
 
 ```pycon
->>> from htpy import li, Fragment
->>> for chunk in fragment[li["a"], li["b"]]:
+>>> from htpy import li, fragment
+>>> for chunk in fragment[li["a"], li["b"]].stream_chunks():
 ...     print(f"got a chunk: {chunk!r}")
 ...
 got a chunk: '<li>'

htpy/__init__.py

@@ -131,10 +131,18 @@ class ContextProvider(t.Generic[T]):
     node: Node
 
     def __iter__(self) -> Iterator[str]:
-        return iter_node(self)
+        return _stream_chunks(self, {})
 
-    def __str__(self) -> str:
-        return render_node(self)
+    def __str__(self) -> _Markup:
+        return _as_markup(self)
+
+    __html__ = __str__
+
+    def stream_chunks(self) -> Iterator[str]:
+        return _stream_chunks(self, {})
+
+    def encode(self, encoding: str = "utf-8", errors: str = "strict") -> bytes:
+        return str(self).encode(encoding, errors)
 
 
 @dataclasses.dataclass(frozen=True)
@@ -143,6 +151,17 @@ class ContextConsumer(t.Generic[T]):
     debug_name: str
     func: Callable[[T], Node]
 
+    def __str__(self) -> _Markup:
+        return _as_markup(self)
+
+    __html__ = __str__
+
+    def stream_chunks(self) -> Iterator[str]:
+        return _stream_chunks(self, {})
+
+    def encode(self, encoding: str = "utf-8", errors: str = "strict") -> bytes:
+        return str(self).encode(encoding, errors)
+
 
 class _NO_DEFAULT:
     pass
@@ -168,10 +187,10 @@ def wrapper(*args: P.args, **kwargs: P.kwargs) -> ContextConsumer[T]:
 
 
 def iter_node(x: Node) -> Iterator[str]:
-    return _iter_node_context(x, {})
+    return fragment[x].stream_chunks()
 
 
-def _iter_node_context(x: Node, context_dict: dict[Context[t.Any], t.Any]) -> Iterator[str]:
+def _stream_chunks(x: Node, context_dict: dict[Context[t.Any], t.Any]) -> Iterator[str]:
     while not isinstance(x, BaseElement) and callable(x):
         x = x()
 
@@ -187,24 +206,25 @@ def _iter_node_context(x: Node, context_dict: dict[Context[t.Any], t.Any]) -> It
     if isinstance(x, BaseElement):
         yield from x._iter_context(context_dict)  # pyright: ignore [reportPrivateUsage]
     elif isinstance(x, ContextProvider):
-        yield from _iter_node_context(x.node, {**context_dict, x.context: x.value})  # pyright: ignore [reportUnknownMemberType]
+        yield from _stream_chunks(x.node, {**context_dict, x.context: x.value})  # pyright: ignore [reportUnknownMemberType]
     elif isinstance(x, ContextConsumer):
-        context_value = context_dict.get(x.context, x.context.default)
+        context_value = context_dict.get(x.context, x.context.default)  # pyright: ignore
+
         if context_value is _NO_DEFAULT:
             raise LookupError(
-                f'Context value for "{x.context.name}" does not exist, '
+                f'Context value for "{x.context.name}" does not exist, '  # pyright: ignore
                 f"requested by {x.debug_name}()."
             )
-        yield from _iter_node_context(x.func(context_value), context_dict)
+        yield from _stream_chunks(x.func(context_value), context_dict)  # pyright: ignore
     elif isinstance(x, Fragment):
-        yield from _iter_node_context(x._node, context_dict)  # pyright: ignore
+        yield from _stream_chunks(x._node, context_dict)  # pyright: ignore
     elif isinstance(x, str | _HasHtml):
         yield str(_escape(x))
     elif isinstance(x, int):
         yield str(x)
     elif isinstance(x, Iterable) and not isinstance(x, _KnownInvalidChildren):  # pyright: ignore [reportUnnecessaryIsInstance]
         for child in x:
-            yield from _iter_node_context(child, context_dict)
+            yield from _stream_chunks(child, context_dict)
     else:
         raise TypeError(f"{x!r} is not a valid child element")
 
@@ -231,7 +251,7 @@ def __init__(self, name: str, attrs_str: str = "", children: Node = None) -> Non
         self._children = children
 
     def __str__(self) -> _Markup:
-        return _Markup("".join(self))
+        return _as_markup(self)
 
     __html__ = __str__
 
@@ -281,14 +301,14 @@ def __call__(self: BaseElementSelf, *args: t.Any, **kwargs: t.Any) -> BaseElemen
     def __iter__(self) -> Iterator[str]:
         return self._iter_context({})
 
+    def stream_chunks(self) -> Iterator[str]:
+        return self._iter_context({})
+
     def _iter_context(self, ctx: dict[Context[t.Any], t.Any]) -> Iterator[str]:
         yield f"<{self._name}{self._attrs}>"
-        yield from _iter_node_context(self._children, ctx)
+        yield from _stream_chunks(self._children, ctx)
         yield f"</{self._name}>"
 
-    # Allow starlette Response.render to directly render this element without
-    # explicitly casting to str:
-    # https://github.com/encode/starlette/blob/5ed55c441126687106109a3f5e051176f88cd3e6/starlette/responses.py#L44-L49
     def encode(self, encoding: str = "utf-8", errors: str = "strict") -> bytes:
         return str(self).encode(encoding, errors)
 
@@ -358,13 +378,19 @@ def __init__(self) -> None:
         self._node: Node = None
 
     def __iter__(self) -> Iterator[str]:
-        return iter_node(self)
+        return _stream_chunks(self, {})
 
-    def __str__(self) -> str:
-        return render_node(self)
+    def __str__(self) -> _Markup:
+        return _as_markup(self)
 
     __html__ = __str__
 
+    def stream_chunks(self) -> Iterator[str]:
+        return _stream_chunks(self, {})
+
+    def encode(self, encoding: str = "utf-8", errors: str = "strict") -> bytes:
+        return str(self).encode(encoding, errors)
+
 
 class _FragmentGetter:
     def __getitem__(self, node: Node) -> Fragment:
@@ -376,8 +402,12 @@ def __getitem__(self, node: Node) -> Fragment:
 fragment = _FragmentGetter()
 
 
+def _as_markup(renderable: Renderable) -> _Markup:
+    return _Markup("".join(renderable.stream_chunks()))
+
+
 def render_node(node: Node) -> _Markup:
-    return _Markup("".join(iter_node(node)))
+    return _Markup(fragment[node])
 
 
 def comment(text: str) -> Fragment:
@@ -545,3 +575,14 @@ def __html__(self) -> str: ...
     | Callable
     | Iterable
 )
+
+
+class Renderable(t.Protocol):
+    def __str__(self) -> _Markup: ...
+    def __html__(self) -> _Markup: ...
+    def stream_chunks(self) -> Iterator[str]: ...
+
+    # Allow starlette Response.render to directly render this element without
+    # explicitly casting to str:
+    # https://github.com/encode/starlette/blob/5ed55c441126687106109a3f5e051176f88cd3e6/starlette/responses.py#L44-L49
+    def encode(self, encoding: str = "utf-8", errors: str = "strict") -> bytes: ...

htpy/django.py

@@ -5,7 +5,7 @@
 from django.template import Context, TemplateDoesNotExist
 from django.utils.module_loading import import_string
 
-from . import Element, render_node
+from . import Element, fragment
 
 if t.TYPE_CHECKING:
     from collections.abc import Callable
@@ -19,7 +19,7 @@ def __init__(self, func: Callable[[Context | None, HttpRequest | None], Element]
         self.func = func
 
     def render(self, context: Context | None, request: HttpRequest | None) -> str:
-        return render_node(self.func(context, request))
+        return str(fragment[self.func(context, request)])
 
 
 class HtpyTemplateBackend:

tests/conftest.py

@@ -5,7 +5,7 @@
 
 import pytest
 
-from htpy import Node, iter_node
+import htpy as h
 
 if t.TYPE_CHECKING:
     from collections.abc import Callable, Generator
@@ -17,7 +17,7 @@ class Trace:
 
 
 RenderResult: t.TypeAlias = list[str | Trace]
-RenderFixture: t.TypeAlias = t.Callable[[Node], RenderResult]
+RenderFixture: t.TypeAlias = t.Callable[[h.Renderable], RenderResult]
 TraceFixture: t.TypeAlias = t.Callable[[str], None]
 
 
@@ -52,14 +52,14 @@ def func(description: str) -> None:
 def render(render_result: RenderResult) -> Generator[RenderFixture, None, None]:
     called = False
 
-    def func(node: Node) -> RenderResult:
+    def func(renderable: h.Renderable) -> RenderResult:
         nonlocal called
 
         if called:
             raise AssertionError("render() must only be called once per test")
 
         called = True
-        for chunk in iter_node(node):
+        for chunk in renderable.stream_chunks():
             render_result.append(chunk)
 
         return render_result

tests/test_comment.py

@@ -22,7 +22,3 @@ def test_escape_three_dashes(render: RenderFixture) -> None:
 
 def test_escape_four_dashes(render: RenderFixture) -> None:
     assert render(div[comment("foo----bar")]) == ["<div>", "<!-- foobar -->", "</div>"]
-
-
-def test_str() -> None:
-    assert str(comment("foo")) == "<!-- foo -->"

tests/test_context.py

@@ -2,7 +2,6 @@
 
 import typing as t
 
-import markupsafe
 import pytest
 
 from htpy import Context, Node, div, fragment
@@ -34,19 +33,6 @@ def test_context_provider(render: RenderFixture) -> None:
     assert render(result) == ["<div>", "Hello: c!", "</div>"]
 
 
-class Test_provider_outer_api:
-    """Ensure provider implements __iter__/__str__"""
-
-    def test_iter(self) -> None:
-        result = letter_ctx.provider("c", div[display_letter("Hello")])
-        assert list(result) == ["<div>", "Hello: c!", "</div>"]
-
-    def test_str(self) -> None:
-        result = str(letter_ctx.provider("c", div[display_letter("Hello")]))
-        assert result == "<div>Hello: c!</div>"
-        assert isinstance(result, markupsafe.Markup)
-
-
 def test_no_default(render: RenderFixture) -> None:
     with pytest.raises(
         LookupError,

tests/test_element.py

@@ -26,13 +26,6 @@ def test_void_element_repr() -> None:
     assert repr(htpy.hr("#a")) == """<VoidElement '<hr id="a">'>"""
 
 
-def test_markup_str() -> None:
-    result = str(div(id="a"))
-    assert isinstance(result, str)
-    assert isinstance(result, markupsafe.Markup)
-    assert result == '<div id="a"></div>'
-
-
 def test_element_type() -> None:
     assert_type(div, Element)
     assert isinstance(div, Element)
@@ -44,13 +37,6 @@ def test_element_type() -> None:
     assert isinstance(div()["a"], Element)
 
 
-def test_html_protocol() -> None:
-    element = div["test"]
-    result = element.__html__()
-    assert result == "<div>test</div>"
-    assert isinstance(result, markupsafe.Markup)
-
-
 def test_markupsafe_escape() -> None:
     result = markupsafe.escape(div["test"])
     assert result == "<div>test</div>"

tests/test_legacy_render.py

@@ -0,0 +1,18 @@
+from markupsafe import Markup
+
+from htpy import iter_node, p, render_node
+
+
+def test_render_node() -> None:
+    result = render_node(p["hi"])
+    assert isinstance(result, Markup)
+
+
+def test_iter_node() -> None:
+    result = list(iter_node(p["hi"]))
+    assert result == ["<p>", "hi", "</p>"]
+
+
+def test_element_iter() -> None:
+    result = list(p["hi"])
+    assert result == ["<p>", "hi", "</p>"]