Add @with_children decorator

[jodal]

This adds the @with_children decorator as discussed in #98.

I've kept the implementation in a file of its own, but imported it into the htpy namespace for easy usage.

The docs have not been updated, as I wanted to get this out there for discussion and tweaks first.

TODO

• Tests
• Implementation
• Documentation
• Changelog

[jodal]

I went ahead and added a suggestion for a new section in the docs, so we can get the disussion on that part rolling as well.

[jodal]

Have you had the chance to have a look at this?

[pelme]

Hi @jodal , thanks for creating this PR! I ;eft some small comments. I think it looks good overall. I think it is a good idea that with_children has its own file.

Would be happy if another @with_component user had a look too :) /cc @bessey @davepeck

[jodal]

Rebased on top of 25.5.0.

[pelme]

This looks good to me but would be happy if another @with_children user reviewed it too :)

[jodal]

Thanks for having a second look!

I know that @davepeck has this on his list 😇

[jodal]

Rebased after merge of #119.

[pelme]

cc @Majsvaffla

[davepeck]

@jodal This is great! I ripped out my home-spun @with_children in a project I'm working on and replaced it with yours; all was well, including type checking.

One thing that might be worth documenting is how to layer context consumers and @with_children:

from dataclasses import dataclass
import htpy as h

@dataclass(frozen=True)
class User:
    name: str
    email: str


USER_CONTEXT: h.Context[User | None] = h.Context("user", default=None)

@h.with_children
@USER_CONTEXT.consumer
def UserCard(user: User | None, children: h.Node, *, extra: str) -> h.Renderable:
    ...

I don't tend to use contexts personally, but there you have it.

FWIW, I think @with_children is a natural enough pattern (with a tricky enough implementation, particularly where type hints are concerned) that I'd love to see it find its way into htpy proper.

PS: Sorry it took so long to get back to this. PyCon needed extra recovery time. :-)

[jodal]

I've fixed the typo @Majsvaffla found and added a paragraph and an example about how to combine context consumers and @with_children, as suggested by @davepeck.

[pelme]

awesome, thanks! 🙌