@with_children decorator implementing Renderable

[jodal]

Background and requirements

As several others before us, we also like building custom htpy components that work just like the "native" htpy elements. That is, to make custom components that are not just regular functions:

def my_component(*, title: str, children: h.Node) -> h.Element:
    ...

my_component(title="My title", children=h.div["My content"])

But instead make components that can accept children elements through __getitem__():

@with_children
def my_component(children: h.Node, *, title: str) -> h.Element:
    ...

my_component(title="My title")[h.div["My content"]]

We wanted all of these to work anywhere a component can be used:

my_component                                  # No arguments or children
my_component(title="My title")                # Arguments, but no children
my_component["My content"]                    # No arguments, only children
my_component(title="My title")["My content"]  # Both arguments and children

And finally, with the Renderable protocol (#92) around the corner, it should also be supported:

str(my_component(title="My title")["My content"])           # Render all at once
my_component(title="My title")["My content"].iter_chunks()  # Streaming rendering

Implementation

Here is our implementation with tests. It should work both with the current htpy release and the upcoming one with Renderable support. Once #92 is released, the type bounds for R should be changed from htpy.Node to htpy.Renderable.

htpy_with_children.py

from __future__ import annotations

import functools
from collections.abc import Callable, Iterator, Mapping
from typing import Any, Concatenate

import htpy


class _WithChildrenUnbound[C: htpy.Node, **P, R: htpy.Node]:
    """Decorator to make a component support children nodes.

    This decorator is used to create a component that can accept children nodes,
    just like native htpy components.

    It lets you convert this:

    ```python
    def my_component(*, title: str, children: h.Node) -> h.Element:
        ...

    my_component(title="My title", children=h.div["My content"])
    ```

    To this:

    ```python
    @with_children
    def my_component(children: h.Node, *, title: str) -> h.Element:
        ...

    my_component(title="My title")[h.div["My content"]]
    ```
    """

    wrapped: Callable[Concatenate[C | None, P], R]

    def __init__(self, func: Callable[Concatenate[C | None, P], R]) -> None:
        # This instance is created at import time when decorating the component.
        # It means that this object is global, and shared between all renderings
        # of the same component.
        self.wrapped = func
        functools.update_wrapper(self, func)

    def __repr__(self) -> str:
        return f"with_children({self.wrapped.__name__}, <unbound>)"

    def __call__(
        self, *args: P.args, **kwargs: P.kwargs
    ) -> _WithChildrenBound[C, P, R]:
        # This is the first call to the component, where we get the
        # component's args and kwargs:
        #
        #     my_component(title="My title")
        #
        # It is important that we return a new instance bound to the args
        # and kwargs instead of mutating, so that state doesn't leak between
        # multiple renderings of the same component.
        #
        return _WithChildrenBound(self.wrapped, args, kwargs)

    def __getitem__(self, children: C | None) -> R:
        # This is the unbound component being used with children:
        #
        #     my_component["My content"]
        #
        return self.wrapped(children)  # pyright: ignore[reportCallIssue]

    def __str__(self) -> str:
        # This is the unbound component being rendered to a string:
        #
        #     str(my_component)
        #
        return str(self.wrapped(None))  # pyright: ignore[reportCallIssue, reportArgumentType]

    __html__ = __str__

    def encode(self, encoding: str = "utf-8", errors: str = "strict") -> bytes:
        return str(self).encode(encoding, errors)

    def iter_chunks(self) -> Iterator[str]:
        return self.wrapped(None).iter_chunks()  # pyright: ignore


class _WithChildrenBound[C: htpy.Node, **P, R: htpy.Node]:
    _func: Callable[Concatenate[C | None, P], R]
    _args: tuple[Any, ...]
    _kwargs: Mapping[str, Any]

    def __init__(
        self,
        func: Callable[Concatenate[C | None, P], R],
        args: tuple[Any, ...],
        kwargs: Mapping[str, Any],
    ) -> None:
        # This is called at runtime when the component is being passed args and
        # kwargs. This instance is only used for the current rendering of the
        # component.
        self._func = func
        self._args = args
        self._kwargs = kwargs

    def __repr__(self) -> str:
        return f"with_children({self._func.__name__}, {self._args}, {self._kwargs})"

    def __getitem__(self, children: C | None) -> R:
        # This is a bound component being used with children:
        #
        #     my_component(title="My title")["My content"]
        #
        return self._func(children, *self._args, **self._kwargs)

    def __str__(self) -> str:
        # This is a bound component being rendered to a string:
        #
        #     str(my_component(title="My title"))
        #
        return str(self._func(None, *self._args, **self._kwargs))

    __html__ = __str__

    def encode(self, encoding: str = "utf-8", errors: str = "strict") -> bytes:
        return str(self).encode(encoding, errors)

    def iter_chunks(self) -> Iterator[str]:
        return self._func(None, *self._args, **self._kwargs).iter_chunks()  # pyright: ignore


with_children = _WithChildrenUnbound

test_htpy_with_children.py

from importlib.metadata import version
from typing import Any

import htpy as h
import pytest

from htpy_with_children import with_children


@with_children
def my_component(
    content: h.Node,
    *,
    title: str = "Default title",
) -> h.Element:
    return h.div[
        h.h1[title],
        h.p[content],
    ]


@pytest.mark.parametrize(
    ("component", "expected"),
    [
        (
            my_component,
            "with_children(my_component, <unbound>)",
        ),
        (
            my_component(title="My title"),
            "with_children(my_component, (), {'title': 'My title'})",
        ),
    ],
)
def test_with_children_repr(component: Any, expected: str) -> None:
    assert repr(component) == expected


@pytest.mark.parametrize(
    ("component", "expected"),
    [
        (
            my_component,
            "<div><h1>Default title</h1><p></p></div>",
        ),
        (
            my_component["My ", "content"],
            "<div><h1>Default title</h1><p>My content</p></div>",
        ),
        (
            my_component(title="My title"),
            "<div><h1>My title</h1><p></p></div>",
        ),
        (
            my_component(title="My title")["My ", "content"],
            "<div><h1>My title</h1><p>My content</p></div>",
        ),
    ],
)
def test_with_children_str(component: Any, expected: str) -> None:
    assert str(component) == expected


@pytest.mark.parametrize(
    ("component", "expected"),
    [
        (
            my_component,
            "<div><h1>Default title</h1><p></p></div>",
        ),
        (
            my_component["My ", "content"],
            "<div><h1>Default title</h1><p>My content</p></div>",
        ),
        (
            my_component(title="My title"),
            "<div><h1>My title</h1><p></p></div>",
        ),
        (
            my_component(title="My title")["My ", "content"],
            "<div><h1>My title</h1><p>My content</p></div>",
        ),
    ],
)
def test_with_children_html(component: Any, expected: str) -> None:
    assert component.__html__() == expected


@pytest.mark.parametrize(
    ("component", "expected"),
    [
        (
            my_component,
            b"<div><h1>Default title</h1><p></p></div>",
        ),
        (
            my_component["My ", "content"],
            b"<div><h1>Default title</h1><p>My content</p></div>",
        ),
        (
            my_component(title="My title"),
            b"<div><h1>My title</h1><p></p></div>",
        ),
        (
            my_component(title="My title")["My ", "content"],
            b"<div><h1>My title</h1><p>My content</p></div>",
        ),
    ],
)
def test_with_children_encode(component: Any, expected: str) -> None:
    assert component.encode() == expected


@pytest.mark.skipif(
    version("htpy") < "25.4.0",
    reason="Requires the htpy.Renderable protocol.",
)
@pytest.mark.parametrize(
    ("component", "expected"),
    [
        (
            my_component,
            ["<div>", "<h1>", "Default title", "</h1>", "<p>", "</p>", "</div>"],
        ),
        (
            my_component["My ", "content"],
            [
                "<div>",
                "<h1>",
                "Default title",
                "</h1>",
                "<p>",
                "My ",
                "content",
                "</p>",
                "</div>",
            ],
        ),
        (
            my_component(title="My title"),
            ["<div>", "<h1>", "My title", "</h1>", "<p>", "</p>", "</div>"],
        ),
        (
            my_component(title="My title")["My ", "content"],
            [
                "<div>",
                "<h1>",
                "My title",
                "</h1>",
                "<p>",
                "My ",
                "content",
                "</p>",
                "</div>",
            ],
        ),
    ],
)
def test_with_children_iter_chunks(component: Any, expected: str) -> None:
    assert list(component.iter_chunks()) == expected

Future

If there is interest in having this as part of htpy, that would be awesome.

If not, and there is interest in having something like this around without having to copy or reimplement it in every project, I'm open to maintaining this as a separate Python package.

Is this a pattern many of us use? Is this implementation everything we want, or is there anything missing? Let me know what you think.

[pelme]

Thanks for picking up the discussion and implementing this such that it covers all possible invokation methods and being compatible with Renderable!

I want htpy to be kind of neutral about how to write components/structure your code and encourage make use of regular Python constructs and treat htpy components just like any other code you write. That said, I also do not want everyone to reinvent the patterns by themselves. But I am not exactly sure where to draw the line on what is too opinionated.

It is clear that there are interest in @with_children and a good implementation of it is way to hard to come up with. It is unreasonable to expect every project to make it by themselves. Also copy/pasting things is just annoying (why cant itertools recipes just be part of itertools instead of the docs?!).

So I am not against adding it to htpy and would not be against adding more helpers in the future if there is some kind of consensus about it. Feel free to open a PR if you like and we can continue the discussions there.

/cc @bessey @davepeck

[jodal]

I'll open a PR as soon as #92 has landed. That way we an get a bit better typing right away.

[jodal]

I've opened PR #113 for further discussion now.

[jodal]

@with_children was released in htpy 25.5.1.