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 the iter_chunks() method which is identical with
`__iter__()` but with a better name.

With the introduction of Fragment, this commit makes render_node and
iter_node redundant.

This commit deprecates render_node, iter_node and direct iteration of elements.

More info: #86 (comment)

Author: pelme

docs/changelog.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## NEXT
+- Add the `Renderable` protocol, a consistent API to render an `htpy` object as HTML or to iterate over it. `Element`, `Fragment`, `ContextProvider`, and `ContextConsumer` are all `Renderable`.
+- Deprecate `render_node()` and `iter_node()` and direct iteration over elements. Call `Renderable.__str__()` or `Renderable.iter_chunks()` instead. [Read the Usage docs for more details](usage.md#renderable).
+
 ## 25.4.0 - 2025-04-10
 - Make Context's repr debug friendly [PR #96](https://github.com/pelme/htpy/pull/96). Thanks to Stein Magnus Jodal ([@jodal](https://github.com/jodal)).
 - Strip whitespace around id and class values in CSS selector. Fixes

docs/static-typing.md

@@ -47,6 +47,27 @@ def bootstrap_badge(
 
 ```
 
+## Renderable
+
+htpy elements, fragments and context objects provides are "renderable". The `Renderable` type provides a consistent API to render a `htpy` object as HTML.
+
+The `Renderable` protocol defines these methods:
+
+ - `.__str__()` - render as a HTML string by calling `str()`
+ - `.__html__()`  - render as a HTML string that is safe to use as markup. This makes it possible to directly embed a `Renderable` object in [Django/Jinja templates](django.md#using-htpy-as-part-of-an-existing-django-template).
+ - `.iter_chunks()` - stream the contents as string "chunks". See [Streaming](streaming.md) for more information.
+
+All `Renderable`'s are also `Node`'s and can always be used as a child element. You can use this to write reusable components that can be used as a child node but also be rendered by themselves or embedded into a Django or Jinja template:
+
+```pycon
+>>> from htpy import div, h1, Renderable
+>>> def my_component(name: str) -> Renderable:
+...     return div[h1[f"Hello {name}!"]]
+>>> print(my_component("Dave"))
+<div><h1>Hello Dave!</h1></div>
+
+```
+
 ## Node
 
 `Node` is a type alias for all possible objects that can be used as a child

docs/usage.md

@@ -163,7 +163,7 @@ library. markupsafe is a dependency of htpy and is automatically installed:
 
 ```
 
-If you are generating [Markdown](https://pypi.org/project/Markdown/) and want to insert it into an element, 
+If you are generating [Markdown](https://pypi.org/project/Markdown/) and want to insert it into an element,
 use `Markup` to mark it as safe:
 
 ```pycon title="Injecting generated markdown"
@@ -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 `iter_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"]].iter_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"]].iter_chunks():
 ...     print(f"got a chunk: {chunk!r}")
 ...
 got a chunk: '<li>'
@@ -427,10 +425,10 @@ React.
 Using contexts in htpy involves:
 
 - Creating a context object with `my_context = Context(name[, *, default])` to
-define the type and optional default value of a context variable.
+  define the type and optional default value of a context variable.
 - Using `my_context.provider(value, children)` to set the value of a context variable for a subtree.
 - Adding the `@my_context.consumer` decorator to a component that requires the
-context value. The decorator will add the context value as the first argument to the decorated function:
+  context value. The decorator will add the context value as the first argument to the decorated function:
 
 The `Context` class is a generic and fully supports static type checking.
 
@@ -456,16 +454,16 @@ def my_component(a, b):
 This example shows how context can be used to pass data between components:
 
 - `theme_context: Context[Theme] = Context("theme", default="light")` creates a
-context object that can later be used to define/retrieve the value. In this
-case, `"light"` acts as the default value if no other value is provided.
+  context object that can later be used to define/retrieve the value. In this
+  case, `"light"` acts as the default value if no other value is provided.
 - `theme_context.provider(value, subtree)` defines the value of the
-`theme_context` for the subtree. In this case the value is set to `"dark"` which
-overrides the default value.
+  `theme_context` for the subtree. In this case the value is set to `"dark"` which
+  overrides the default value.
 - The `sidebar` component uses the `@theme_context.consumer` decorator. This
-will make htpy pass the current context value as the first argument to the
-component function.
+  will make htpy pass the current context value as the first argument to the
+  component function.
 - In this example, a `Theme` type is used to ensure that the correct types are
-used when providing the value as well as when it is consumed.
+  used when providing the value as well as when it is consumed.
 
 ```py
 from typing import Literal
@@ -498,5 +496,8 @@ print(my_page())
 Output:
 
 ```html
-<div><h1>Hello!</h1><div class="theme-dark">The Sidebar!</div></div>
+<div>
+  <h1>Hello!</h1>
+  <div class="theme-dark">The Sidebar!</div>
+</div>
 ```

htpy/__init__.py

@@ -9,6 +9,11 @@
 from markupsafe import Markup as _Markup
 from markupsafe import escape as _escape
 
+try:
+    from typing import deprecated  # type: ignore[attr-defined]
+except ImportError:
+    from typing_extensions import deprecated
+
 if t.TYPE_CHECKING:
     from types import UnionType
 
@@ -130,11 +135,26 @@ class ContextProvider(t.Generic[T]):
     value: T
     node: Node
 
+    @deprecated(
+        "iterating over a context provider is deprecated and will be removed in a future release. "
+        "Please use the context_provider.iter_chunks() method instead."
+    )  # pyright: ignore [reportUntypedFunctionDecorator]
     def __iter__(self) -> Iterator[str]:
-        return iter_node(self)
+        return self.iter_chunks()
+
+    def __str__(self) -> _Markup:
+        return _as_markup(self)
 
-    def __str__(self) -> str:
-        return render_node(self)
+    __html__ = __str__
+
+    def iter_chunks(self) -> Iterator[str]:
+        return self._iter_chunks_context({})
+
+    def encode(self, encoding: str = "utf-8", errors: str = "strict") -> bytes:
+        return str(self).encode(encoding, errors)
+
+    def _iter_chunks_context(self, context: dict[Context[t.Any], t.Any]) -> Iterator[str]:
+        yield from _iter_chunks_node(self.node, {**context, self.context: self.value})  # pyright: ignore [reportUnknownMemberType]
 
 
 @dataclasses.dataclass(frozen=True)
@@ -143,6 +163,27 @@ class ContextConsumer(t.Generic[T]):
     debug_name: str
     func: Callable[[T], Node]
 
+    def __str__(self) -> _Markup:
+        return _as_markup(self)
+
+    __html__ = __str__
+
+    def iter_chunks(self) -> Iterator[str]:
+        return self._iter_chunks_context({})
+
+    def encode(self, encoding: str = "utf-8", errors: str = "strict") -> bytes:
+        return str(self).encode(encoding, errors)
+
+    def _iter_chunks_context(self, context: dict[Context[t.Any], t.Any]) -> Iterator[str]:
+        context_value = context.get(self.context, self.context.default)
+
+        if context_value is _NO_DEFAULT:
+            raise LookupError(
+                f'Context value for "{self.context.name}" does not exist, '  # pyright: ignore
+                f"requested by {self.debug_name}()."
+            )
+        yield from _iter_chunks_node(self.func(context_value), context)  # pyright: ignore
+
 
 class _NO_DEFAULT:
     pass
@@ -168,11 +209,15 @@ def wrapper(*args: P.args, **kwargs: P.kwargs) -> ContextConsumer[T]:
         return wrapper
 
 
+@deprecated(
+    "iter_node is deprecated and will be removed in a future release. "
+    "Please use the .iter_chunks() method on elements/fragments instead."
+)  # pyright: ignore [reportUntypedFunctionDecorator]
 def iter_node(x: Node) -> Iterator[str]:
-    return _iter_node_context(x, {})
+    return fragment[x].iter_chunks()
 
 
-def _iter_node_context(x: Node, context_dict: dict[Context[t.Any], t.Any]) -> Iterator[str]:
+def _iter_chunks_node(x: Node, context: dict[Context[t.Any], t.Any]) -> Iterator[str]:
     while not isinstance(x, BaseElement) and callable(x):
         x = x()
 
@@ -185,27 +230,16 @@ def _iter_node_context(x: Node, context_dict: dict[Context[t.Any], t.Any]) -> It
     if x is False:
         return
 
-    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]
-    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}()."
-            )
-        yield from _iter_node_context(x.func(context_value), context_dict)
-    elif isinstance(x, Fragment):
-        yield from _iter_node_context(x._node, context_dict)  # pyright: ignore
+    if hasattr(x, "_iter_chunks_context"):
+        yield from x._iter_chunks_context(context)  # 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 _iter_chunks_node(child, context)
     else:
         raise TypeError(f"{x!r} is not a valid child element")
 
@@ -232,7 +266,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__
 
@@ -279,17 +313,21 @@ def __call__(self: BaseElementSelf, *args: t.Any, **kwargs: t.Any) -> BaseElemen
             self._children,
         )
 
+    @deprecated(
+        "iterating over an element is deprecated and will be removed in a future release. "
+        "Please use the element.iter_chunks() method instead."
+    )  # pyright: ignore [reportUntypedFunctionDecorator]
     def __iter__(self) -> Iterator[str]:
-        return self._iter_context({})
+        return self.iter_chunks()
 
-    def _iter_context(self, ctx: dict[Context[t.Any], t.Any]) -> Iterator[str]:
+    def iter_chunks(self) -> Iterator[str]:
+        return self._iter_chunks_context({})
+
+    def _iter_chunks_context(self, context: dict[Context[t.Any], t.Any]) -> Iterator[str]:
         yield f"<{self._name}{self._attrs}>"
-        yield from _iter_node_context(self._children, ctx)
+        yield from _iter_chunks_node(self._children, context)
         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)
 
@@ -334,13 +372,13 @@ def __repr__(self) -> str:
 
 
 class HTMLElement(Element):
-    def _iter_context(self, ctx: dict[Context[t.Any], t.Any]) -> Iterator[str]:
+    def _iter_chunks_context(self, context: dict[Context[t.Any], t.Any]) -> Iterator[str]:
         yield "<!doctype html>"
-        yield from super()._iter_context(ctx)
+        yield from super()._iter_chunks_context(context)
 
 
 class VoidElement(BaseElement):
-    def _iter_context(self, ctx: dict[Context[t.Any], t.Any]) -> Iterator[str]:
+    def _iter_chunks_context(self, context: dict[Context[t.Any], t.Any]) -> Iterator[str]:
         yield f"<{self._name}{self._attrs}>"
 
     def __repr__(self) -> str:
@@ -358,14 +396,27 @@ def __init__(self) -> None:
         # node directly via the constructor.
         self._node: Node = None
 
+    @deprecated(
+        "iterating over a fragment is deprecated and will be removed in a future release. "
+        "Please use the fragment.iter_chunks() method instead."
+    )  # pyright: ignore [reportUntypedFunctionDecorator]
     def __iter__(self) -> Iterator[str]:
-        return iter_node(self)
+        return self.iter_chunks()
 
-    def __str__(self) -> str:
-        return render_node(self)
+    def __str__(self) -> _Markup:
+        return _as_markup(self)
 
     __html__ = __str__
 
+    def iter_chunks(self) -> Iterator[str]:
+        return self._iter_chunks_context({})
+
+    def encode(self, encoding: str = "utf-8", errors: str = "strict") -> bytes:
+        return str(self).encode(encoding, errors)
+
+    def _iter_chunks_context(self, context: dict[Context[t.Any], t.Any]) -> Iterator[str]:
+        yield from _iter_chunks_node(self._node, context)
+
 
 class _FragmentGetter:
     def __getitem__(self, node: Node) -> Fragment:
@@ -377,8 +428,16 @@ def __getitem__(self, node: Node) -> Fragment:
 fragment = _FragmentGetter()
 
 
+def _as_markup(renderable: Renderable) -> _Markup:
+    return _Markup("".join(renderable.iter_chunks()))
+
+
+@deprecated(
+    "render_node is deprecated and will be removed in a future release. "
+    "Please use Renderable.__str__() instead."
+)  # pyright: ignore [reportUntypedFunctionDecorator]
 def render_node(node: Node) -> _Markup:
-    return _Markup("".join(iter_node(node)))
+    return _Markup(fragment[node])
 
 
 def comment(text: str) -> Fragment:
@@ -391,20 +450,28 @@ class _HasHtml(t.Protocol):
     def __html__(self) -> str: ...
 
 
+class Renderable(t.Protocol):
+    def __str__(self) -> _Markup: ...
+    def __html__(self) -> _Markup: ...
+    def iter_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: ...
+
+    # The _iter_chunks_context method is called internally to render the element.
+    # This method is not a public API with any backward compatibilty and is
+    # subject to change without any notice. Feel free to use it at your own risk
+    # and report how you use it in a Github issue at https://github.com/pelme/htpy
+    # to encourage turning it into a public API. :)
+    def _iter_chunks_context(self, context: dict[Context[t.Any], t.Any]) -> Iterator[str]: ...
+
+
 _ClassNamesDict: t.TypeAlias = dict[str, bool]
 _ClassNames: t.TypeAlias = Iterable[str | None | bool | _ClassNamesDict] | _ClassNamesDict
 Node: t.TypeAlias = (
-    None
-    | bool
-    | str
-    | int
-    | BaseElement
-    | _HasHtml
-    | Fragment
-    | Iterable["Node"]
-    | Callable[[], "Node"]
-    | ContextProvider[t.Any]
-    | ContextConsumer[t.Any]
+    Renderable | None | bool | str | int | _HasHtml | Iterable["Node"] | Callable[[], "Node"]
 )
 
 Attribute: t.TypeAlias = None | bool | str | int | _HasHtml | _ClassNames