Text templates whose interpolations may be effects or streams (Effect's
Template), for HTML responses.
A template is its literal strings and the values between them, as a tagged template literal gives them; on Python 3.14 a t-string is one too::
template.make(["<p>Hello, ", "!</p>"], current_user_name)
template.make(t"<p>Hello, {current_user_name}!</p>") # Python 3.14A value is a primitive (str, int, float, bool; None
renders as nothing; a sequence renders its items joined), a Some, or an
effect of one. stream also takes streams, and writes each part as soon
as it is known. Effects run concurrently.
Values are inserted as they are, without HTML escaping, as in Effect: a value
holding <script> becomes markup. Escape text that isn't yours first::
from html import escape
template.make(t"<p>Hello, {escape(name)}!</p>")Types#
| Type | Definition | Description |
|---|---|---|
PrimitiveValue | type PrimitiveValue = str | int | float | bool | None | |
Primitive | type Primitive = PrimitiveValue | Sequence[PrimitiveValue] | |
Interpolated | type Interpolated[E = Never, R = Never] = Primitive | Some[Primitive] | Effect[Primitive, E, R] | |
InterpolatedWithStream | type InterpolatedWithStream[E = Never, R = Never] = Interpolated[E, R] | Stream[Primitive, E, R] |
Classes#
Functions#
primitive_to_string#
primitive_to_string(value) -> str| Parameter | Type | Description |
|---|---|---|
value | Primitive |
Returns str
def primitive_to_string(value: Primitive) -> str:
if isinstance(value, str):
return value
if isinstance(value, bool):
return "true" if value else "false"
if isinstance(value, (int, float)):
return js_number(value)
if value is None:
return ""
return "".join(primitive_to_string(item) for item in value)make#
make(strings: TemplateLike, /) -> Effect[str, Any, Any]
make[EE = Never, RR = Never](strings: Sequence[str], /, *args: Interpolated[EE, RR] = ()) -> Effect[str, EE, RR]The text of the template, after running its effects concurrently.
strings holds one more string than there are args.
| Parameter | Type | Description |
|---|---|---|
strings | ||
args | = () |
@overload
def make(strings: TemplateLike, /) -> Effect[str, Any, Any]: ...
@overload
def make[EE = Never, RR = Never](
strings: Sequence[str], /, *args: Interpolated[EE, RR]
) -> Effect[str, EE, RR]: ...
def make(strings: Sequence[str] | TemplateLike, /, *args: object) -> Effect[str, Any, Any]:
"""The text of the template, after running its effects concurrently.
``strings`` holds one more string than there are ``args``."""
texts, values = _parts(strings, args)
rendered = [""] * len(values)
effects: list[tuple[int, Effect[Primitive, Any, Any]]] = []
for index, value in enumerate(values):
if isinstance(value, Some):
rendered[index] = primitive_to_string(cast("Some[Primitive]", value).value)
elif isinstance(value, Effect):
effects.append((index, cast("Effect[Primitive, Any, Any]", value)))
else:
rendered[index] = primitive_to_string(cast("Primitive", value))
if not effects:
return succeed(_consolidate(texts, rendered))
def run(entry: tuple[int, Effect[Primitive, Any, Any]]) -> Effect[None, Any, Any]:
index, effect = entry
def store(value: Primitive) -> None:
rendered[index] = primitive_to_string(value)
return effect.map(store)
return for_each(effects, run, concurrency="unbounded").map(
lambda _: _consolidate(texts, rendered)
)stream#
stream(strings: TemplateLike, /) -> Stream[str, Any, Any]
stream[EE = Never, RR = Never](strings: Sequence[str], /, *args: InterpolatedWithStream[EE, RR] = ()) -> Stream[str, EE, RR]The template's text as it is known, in order: literal text and plain values at once, effects (run concurrently) and streams in their place.
| Parameter | Type | Description |
|---|---|---|
strings | ||
args | = () |
@overload
def stream(strings: TemplateLike, /) -> Stream[str, Any, Any]: ...
@overload
def stream[EE = Never, RR = Never](
strings: Sequence[str], /, *args: InterpolatedWithStream[EE, RR]
) -> Stream[str, EE, RR]: ...
def stream(strings: Sequence[str] | TemplateLike, /, *args: object) -> Stream[str, Any, Any]:
"""The template's text as it is known, in order: literal text and plain
values at once, effects (run concurrently) and streams in their
place."""
texts, values = _parts(strings, args)
chunks: list[_Chunk] = []
buffer = ""
for index, value in enumerate(values):
buffer += texts[index]
if isinstance(value, Some):
buffer += primitive_to_string(cast("Some[Primitive]", value).value)
elif isinstance(value, (Effect, Stream)):
if buffer:
chunks.append(buffer)
buffer = ""
if isinstance(value, Effect):
chunks.append(cast("Effect[Primitive, Any, Any]", value).map(primitive_to_string))
else:
chunks.append(cast("Stream[Primitive, Any, Any]", value).map(primitive_to_string))
else:
buffer += primitive_to_string(cast("Primitive", value))
buffer += texts[-1]
if buffer:
chunks.append(buffer)
def evaluate(chunk: _Chunk) -> Effect[str | Stream[str, Any, Any], Any, Any]:
return chunk if isinstance(chunk, Effect) else succeed(chunk)
def expand(chunk: str | Stream[str, Any, Any]) -> Stream[str, Any, Any]:
return succeed_stream(chunk) if isinstance(chunk, str) else chunk
return from_iterable(chunks).map_effect(evaluate, concurrency="unbounded").flat_map(expand)