Raise exception when rendering a generator twice (#102) (#142)

Generators can only be consumed once. Previously, attempting to render
an element containing a generator multiple times would silently produce
empty output on subsequent renders.

Now raises RuntimeError with clear message when a generator is consumed
twice, preventing this footgun while maintaining performance.

Author: pelme

docs/usage.md

@@ -125,6 +125,20 @@ You can pass a list, tuple or generator to generate multiple children:
     directly when the element is constructed. See [Streaming](streaming.md) for
     more information.
 
+!!! warning "Generator Consumption"
+
+    Generators can only be consumed once. If you try to render an element containing a generator multiple times, you will get a `RuntimeError` on the second attempt:
+
+    ```python
+    >>> element = div[(x for x in "abc")]
+    >>> str(element)  # First render - works
+    '<div>abc</div>'
+    >>> str(element)  # Second render - fails
+    RuntimeError: Generator has already been consumed
+    ```
+
+    If you need to render the same content multiple times, use a `list` instead of a generator.
+
 A `list` can be used similar to a [JSX fragment](https://react.dev/reference/react/Fragment):
 
 ```pycon title="Render a list of child elements"

src/htpy/_rendering.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
 import typing as t
-from collections.abc import Iterable
+import weakref
+from collections.abc import Generator, Iterable
 
 import markupsafe
 
@@ -13,6 +14,9 @@
     from htpy._contexts import Context
     from htpy._types import Node, Renderable
 
+# Track consumed generators to prevent double consumption
+_consumed_generators: weakref.WeakSet[Generator[t.Any, t.Any, t.Any]] = weakref.WeakSet()
+
 
 def chunks_as_markup(renderable: Renderable) -> markupsafe.Markup:
     return markupsafe.Markup("".join(renderable.iter_chunks()))
@@ -39,6 +43,12 @@ def iter_chunks_node(x: Node, context: Mapping[Context[t.Any], t.Any] | None) ->
         yield str(markupsafe.escape(x))
     elif isinstance(x, int):
         yield str(x)
+    elif isinstance(x, Generator):
+        if x in _consumed_generators:
+            raise RuntimeError("Generator has already been consumed")
+        _consumed_generators.add(x)
+        for child in x:
+            yield from iter_chunks_node(child, context)
     elif isinstance(x, Iterable) and not isinstance(x, KnownInvalidChildren):  # pyright: ignore [reportUnnecessaryIsInstance]
         for child in x:
             yield from iter_chunks_node(child, context)

tests/test_children.py

@@ -12,7 +12,21 @@
 from markupsafe import Markup
 from typing_extensions import assert_type
 
-from htpy import Element, VoidElement, dd, div, dl, dt, html, img, input, li, my_custom_element, ul
+from htpy import (
+    Element,
+    VoidElement,
+    dd,
+    div,
+    dl,
+    dt,
+    fragment,
+    html,
+    img,
+    input,
+    li,
+    my_custom_element,
+    ul,
+)
 
 from .conftest import Trace
 
@@ -133,6 +147,17 @@ def test_generator_children(render: RenderFixture) -> None:
     assert render(result) == ["<ul>", "<li>", "a", "</li>", "<li>", "b", "</li>", "</ul>"]
 
 
+def test_raise_error_consume_generator_twice() -> None:
+    def gen() -> Iterator[str]:
+        yield "hi"
+
+    fragment_ = fragment[gen()]
+    assert list(fragment_.iter_chunks()) == ["hi"]
+
+    with pytest.raises(RuntimeError, match="Generator has already been consumed"):
+        list(fragment_.iter_chunks())
+
+
 def test_non_generator_iterator(render: RenderFixture, trace: TraceFixture) -> None:
     result = div[SingleShotIterator("hello", trace=trace)]