Add a consistent rendering protocol.

[pelme]

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)

[davepeck]

I've been playing with these changes (well, after fixing that one lint issue) and: so far, so good. All my "template" functions return h.Renderable now and everything feels that much simpler.

As a random aside: these changes also caused me to slightly update my @with_children decorator, which I still use to make regular functions support __getitem__ and look a bit more like any other htpy Element:

@dataclass(frozen=True)
class with_children[C, R: h.Renderable, **P]:
    """Wrap a function to make it look more like an htpy.Element."""

    _f: t.Callable[t.Concatenate[C, P], R]
    _args: tuple[t.Any, ...] = field(default_factory=tuple)
    _kwargs: t.Mapping[str, t.Any] = field(default_factory=dict)

    def __getitem__(self, children: C) -> R:
        """Render the component with the given children."""
        return self._f(children, *self._args, **self._kwargs)

    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> t.Self:
        """Return a new instance of the class with the given arguments."""
        return replace(self, _args=args, _kwargs=kwargs)

    def __str__(self) -> str:
        """Return the name of the function being wrapped."""
        # CONSIDER: alternatively, invoke the function here? If the function
        # provides a default value for its arguments, it'll work; otherwise,
        # it will blow up... which might be a good thing?
        return f"with_children[{self._f.__name__}]"

[pelme]

@davepeck awesome, thanks for the update! pushed an updated version that fixes the lint problem.

I renamed stream_chunks() to iter_chunks() which I like better, thoughts about that?

I will also add some kind of DeprecationWarning to render_node/iter_node and then hopefully merge this PR in the next few days. Then we can hopefully also get #38 done. Feel free to have a look there too!

[davepeck]

I renamed stream_chunks() to iter_chunks() which I like better, thoughts about that?

I prefer iter_chunks() too!

Then we can hopefully also get #38 done. Feel free to have a look there too!

Will do...

[jodal]

I'm trying to get our version of with_children to work on components that also use contexts. I'm trying to juggle both the current implementation of htpy and these changes in my head at the same time, so that I won't have to redo it once this is merged.

What I'm saying is that I'd love for this to be merged and released, so that I can garbage collect half of my mental state 😅

[pelme]

have not been able to finish up these changes yet, not sure when I will get around to it. if someone wants to look into deprecation warnings for render_node/iter_node and update the docs/changelog, that would be helpful!

[davepeck]

have not been able to finish up these changes yet, not sure when I will get around to it. if someone wants to look into deprecation warnings for render_node/iter_node and update the docs/changelog, that would be helpful!

I took a quick first stab at this: https://github.com/davepeck/htpy/tree/pelme-zsxolror

Tried to match your house style but let me know what's most useful.

(Update: my branch has a couple small updates as of 4/3 @ 9AM Pacific)

[pelme]

I have updated the PR based on you commits @davepeck , I think it may be good to go.

I changed Renderable to be a type alias rather than a Protocol. I think that makes more sense. Then a Renderable can always be a Node.

@davepeck @jodal Can you please have another look?

[davepeck]

I'm really happy where this landed!