Add Fragment node for node grouping (#86)

Author: geigerzaehler

docs/changelog.md

@@ -1,11 +1,15 @@
 # Changelog
 
-# 25.2.0 - 2025-02-01
+## Next (minor)
+- Add a `Fragment` node for explicitly grouping a collection of nodes. Fixes
+[#82](https://github.com/pelme/htpy/issues/82)
+
+## 25.2.0 - 2025-02-01
 - Context providers longer require wrapping nodes in a function/lambda. This
 simplifies context usage while still being backward compatible. Thanks to Thomas
 Scholtes ([@geigerzaehler](https://github.com/geigerzaehler)) for the patch. [PR #83](https://github.com/pelme/htpy/pull/83).
 
-# 25.1.0 - 2025-01-27
+## 25.1.0 - 2025-01-27
 - Adjust typing for attributes: Allow Mapping instead of just dict. Thanks to
 David Svenson ([@Majsvaffla](https://github.com/Majsvaffla)) for the initial report+patch. [PR #80](https://github.com/pelme/htpy/pull/80).
 

docs/usage.md

@@ -92,6 +92,22 @@ You can use this to conditionally render content with inline `and` and
 
 ```
 
+### Fragments
+
+Fragments allow you to wrap a group of nodes (not necessarily elements) so that
+they can be rendered without a wrapping element.
+
+```pycon
+>>> from htpy import p, i, Fragment
+>>> content = Fragment("Hello ", None, i["world!"])
+>>> print(content)
+Hello <i>world!</i>
+
+>>> print(p[content])
+<p>Hello <i>world!</i></p>
+
+```
+
 ### Loops / Iterating Over Children
 
 You can pass a list, tuple or generator to generate multiple children:
@@ -362,31 +378,6 @@ snippets as attributes:
 
 ```
 
-## Render elements without a parent (orphans)
-
-In some cases such as returning partial content it is useful to render elements
-without a parent element. This is useful in HTMX partial responses.
-
-You may use `render_node` to achieve this:
-
-```pycon title="Render elements without a parent"
->>> from htpy import render_node, tr
->>> print(render_node([tr["a"], tr["b"]]))
-<tr>a</tr><tr>b</tr>
-
-```
-
-`render_node()` accepts all kinds of [`Node`](static-typing.md#node) objects.
-You may use it to render anything that would normally be a children of another
-element.
-
-!!! note "Best practice: Only use render_node() to render non-Elements"
-
-    You can render regular elements by using `str()`, e.g. `str(p["hi"])`. While
-    `render_node()` would give the same result, it is more straightforward and
-    better practice to just use `str()` when rendering a regular element. Only
-    use `render_node()` when you do not have a parent element.
-
 ## Iterating of the Output
 
 Iterating over a htpy element will yield the resulting contents in chunks as

htpy/__init__.py

@@ -196,6 +196,9 @@ def _iter_node_context(x: Node, context_dict: dict[Context[t.Any], t.Any]) -> It
                 f"requested by {x.debug_name}()."
             )
         yield from _iter_node_context(x.func(context_value), context_dict)
+    elif isinstance(x, Fragment):
+        for node in x._nodes:  # pyright: ignore [reportPrivateUsage]
+            yield from _iter_node_context(node, context_dict)
     elif isinstance(x, str | _HasHtml):
         yield str(_escape(x))
     elif isinstance(x, int):
@@ -344,13 +347,35 @@ def __repr__(self) -> str:
         return f"<{self.__class__.__name__} '<{self._name}{self._attrs}>'>"
 
 
+class Fragment:
+    """A collection of nodes without a wrapping element.
+
+    >>> content = Fragment("Hello ", None, i["world!"])
+    >>> print(content)
+    Hello <i>world!</i>
+    """
+
+    __slots__ = ("_nodes",)
+
+    def __init__(self, *nodes: Node) -> None:
+        self._nodes = nodes
+
+    def __iter__(self) -> Iterator[str]:
+        return iter_node(self)
+
+    def __str__(self) -> str:
+        return render_node(self)
+
+    __html__ = __str__
+
+
 def render_node(node: Node) -> _Markup:
     return _Markup("".join(iter_node(node)))
 
 
-def comment(text: str) -> _Markup:
+def comment(text: str) -> Fragment:
     escaped_text = text.replace("--", "")
-    return _Markup(f"<!-- {escaped_text} -->")
+    return Fragment(_Markup(f"<!-- {escaped_text} -->"))
 
 
 @t.runtime_checkable
@@ -367,6 +392,7 @@ def __html__(self) -> str: ...
     | int
     | BaseElement
     | _HasHtml
+    | Fragment
     | Iterable["Node"]
     | Callable[[], "Node"]
     | ContextProvider[t.Any]
@@ -507,6 +533,7 @@ def __html__(self) -> str: ...
     | ContextConsumer  # pyright: ignore [reportMissingTypeArgument]
     | str
     | int
+    | Fragment
     | _HasHtml
     | Callable
     | Iterable

tests/test_comment.py

@@ -22,3 +22,7 @@ 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

@@ -5,7 +5,7 @@
 import markupsafe
 import pytest
 
-from htpy import Context, Node, div
+from htpy import Context, Fragment, Node, div
 
 if t.TYPE_CHECKING:
     from .conftest import RenderFixture
@@ -107,3 +107,15 @@ def echo(value: str) -> str:
     result = div[ctx.provider("foo", [echo()])]
 
     assert render(result) == ["<div>", "foo", "</div>"]
+
+
+def test_context_passed_via_fragment(render: RenderFixture) -> None:
+    ctx: Context[str] = Context("ctx")
+
+    @ctx.consumer
+    def echo(value: str) -> str:
+        return value
+
+    result = div[ctx.provider("foo", Fragment(echo()))]
+
+    assert render(result) == ["<div>", "foo", "</div>"]

tests/test_fragment.py

@@ -0,0 +1,43 @@
+import markupsafe
+
+from htpy import Fragment, i, p
+
+from .conftest import RenderFixture
+
+
+def test_render_direct() -> None:
+    assert str(Fragment("Hello ", None, i["World"])) == "Hello <i>World</i>"
+
+
+def test_render_as_child(render: RenderFixture) -> None:
+    assert render(p["Say: ", Fragment("Hello ", None, i["World"]), "!"]) == [
+        "<p>",
+        "Say: ",
+        "Hello ",
+        "<i>",
+        "World",
+        "</i>",
+        "!",
+        "</p>",
+    ]
+
+
+def test_render_nested(render: RenderFixture) -> None:
+    assert render(Fragment(Fragment("Hel", "lo "), "World")) == ["Hel", "lo ", "World"]
+
+
+def test_render_chunks(render: RenderFixture) -> None:
+    assert render(Fragment("Hello ", None, i["World"])) == [
+        "Hello ",
+        "<i>",
+        "World",
+        "</i>",
+    ]
+
+
+def test_safe() -> None:
+    assert markupsafe.escape(Fragment(i["hi"])) == "<i>hi</i>"
+
+
+def test_iter() -> None:
+    assert list(Fragment("Hello ", None, i["World"])) == ["Hello ", "<i>", "World", "</i>"]