Templates

wybthon.templates¶

templates ¶

HTML templates written as t-strings, compiled once per literal.

html turns a PEP 750 template string into a node:

from wybthon import component, create_signal, html


@component
def Counter():
    count, set_count = create_signal(0)

    def increment():
        set_count(lambda n: n + 1)

    return html(t"""
      <div class="counter">
        <p>Count: {count()} (doubled: {count() * 2})</p>
        <button onclick={increment}>+</button>
      </div>
    """)

Wybthon's compiler (wybthon.compiler) prepares each html(t"...") call when its module is compiled: dynamic interpolations ({count() * 2}) become getters, and the literal is parsed, validated, and turned into a mount function ahead of time. A template that reaches html() uncompiled (a REPL, exec) is compiled here on its first call and cached by the identity of its static strings, which a t-string literal shares across evaluations. Either way, this is the counterpart of Solid's JSX compiler:

the static markup becomes one native <template> the kernel clones with a single command per instance, with no VNode tree for its static parts;
each interpolation becomes a slot at a known node offset: a child, an attribute or part of one, an event handler, a ref, a spread of props, or a component tag;
when a reactive hole returns a template from the same literal again, the mounted instance is patched slot by slot.

At run time an interpolation that's an accessor, a getter, or a zero-argument function becomes a reactive binding; anything else is applied once. Server rendering, hydration, and SVG expand the template into ordinary VNodes and mount those.

See the templates guide.

Classes:

Name	Description
`TemplateError`	Raised when a template's markup is malformed or would be rewritten by the HTML parser.

Functions:

Name	Description
`html`	Render a t-string template to a node.

TemplateError ¶

Bases: ValueError

Raised when a template's markup is malformed or would be rewritten by the HTML parser.

html ¶

html(template: Template, compiled: Precompiled | None = None) -> VNode

Render a t-string template to a node.

The template is HTML with interpolations. Each literal is compiled once (see the module docs); later calls only supply values.

Interpolation positions:

Child (<p>{value}</p>): text, a node, a list, None, or a reactive expression (an accessor or zero-argument function), which becomes a hole.
Attribute (<a href={url}>): a value applied once, or a reactive expression bound to that attribute.
Part of an attribute (class="card card-{kind}"): the parts form one string, re-rendered together when any reactive part changes.
Event (onclick={handler}, onClick, or on:click): a delegated handler, taking the event or no arguments.
Spread (<input {attrs}>): a mapping of props.
Component tag (<{Card} title="Hi">...</{Card}> or <{Card} />): calls the component with the attributes as keyword props and the content as children.

Attribute names are HTML names (class, for, aria-label). Text follows JSX's whitespace rules: text spanning lines is trimmed line by line and joined with spaces, and whitespace-only text containing a newline is dropped. Several top-level nodes make a fragment.

Parameters:

Name	Type	Description	Default
`template`	`Template`	A t-string.	required
`compiled`	`Precompiled \| None`	The literal's precompiled entry; the compiler passes it (see `wybthon.compiler`). Don't pass it yourself.	`None`

Returns:

Type	Description
`VNode`	A node to place in the tree or return from a component.

Raises:

Type	Description
`TemplateError`	The markup is malformed, or the HTML parser would rewrite it (for example `<tr>` directly inside `<table>`).

Example

html(t'<li class={"done" if done() else ""}>{title}</li>')

What's in this module¶

templates turns t-string HTML templates into nodes. The compiler parses and validates each literal when its module is compiled, turns its dynamic interpolations into getters, and emits its mount functions as ordinary module code, so html() only rebuilds the slot plan from the precompiled tree on first use. A template that reaches html() uncompiled (a REPL, exec) is parsed and compiled on its first call instead, keyed by the identity of its static strings. See Templates for the full guide.

Name	Description
`html`	Turn a t-string template into a node.
`TemplateError`	Raised for malformed markup, markup the HTML parser would rewrite, or, in dev mode, an uncompiled template whose dynamic expression was evaluated once.