agentcore-cli 0.31.1__py3-none-any.whl

agentcore/templates/_handlebars.py

@@ -0,0 +1,782 @@
+"""Handlebars rendering with handlebars.js 4.7 semantics on top of pybars3.
+
+pybars3 differs from handlebars.js in ways that change the rendered output of the templates:
+
+* its standalone-line removal is a regex approximation of handlebars' ``WhitespaceControl``;
+* it does not parse ``{{else if ...}}`` chains;
+* it does not escape ``=``, its ``unless`` ignores ``{{else}}``, and it uses Python truthiness
+  (``{}`` falsy) and Python ``str()`` (``1.0``, ``[1, 2]``) instead of JavaScript's.
+
+So a template is first lexed and parsed here into handlebars' AST, whitespace control is applied by a
+straight port of ``compiler/whitespace-control.js``, ``else``-chains are desugared into nested
+blocks, and the resulting source (whose whitespace is now final) is compiled by pybars3 with its own
+whitespace handling disabled. At runtime, the compiled module's ``prepare``/``resolve`` globals and the
+built-in block helpers are replaced with JavaScript-faithful versions.
+"""
+
+from __future__ import annotations
+
+import re
+import threading
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from functools import lru_cache
+from typing import Any
+
+import pybars
+from pybars._compiler import Scope, strlist
+
+from agentcore.templates._js import (
+    JS_WS,
+    hb_is_empty,
+    js_object_keys,
+    js_same_value_zero,
+    js_strict_equals,
+    js_to_string,
+    js_truthy,
+    json_stringify,
+    utf16_len,
+)
+
+__all__ = ["SafeString", "TemplateSyntaxError", "compile_template", "render_template"]
+
+
+class TemplateSyntaxError(ValueError):
+    pass
+
+
+class SafeString(strlist):
+    """Helper output that must not be HTML-escaped (``Handlebars.SafeString``)."""
+
+    def __init__(self, value: str) -> None:
+        super().__init__([value])
+
+
+# ---------------------------------------------------------------------------
+# Lexing
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _Strip:
+    open: bool = False
+    close: bool = False
+
+
+@dataclass
+class _Tag:
+    kind: str  # mustache | triple | amp | comment | open | open_inverse | open_chain | inverse | close
+    expr: str
+    strip: _Strip
+
+
+_Token = str | _Tag
+
+_TAG_START = re.compile(r"\{\{(~)?")
+_INVERSE_RE = re.compile(r"(?:\^|" + JS_WS + r"*else)" + JS_WS + r"*(~)?\}\}")
+_CHAIN_RE = re.compile(JS_WS + r"*else\b")
+
+
+def _find_close(source: str, pos: int, closer: str) -> int:
+    """Index of the ``[~]closer`` ending a mustache, skipping string literals."""
+    quote = ""
+    i = pos
+    while i < len(source):
+        ch = source[i]
+        if quote:
+            if ch == "\\" and i + 1 < len(source):
+                i += 2
+                continue
+            if ch == quote:
+                quote = ""
+        elif ch in "\"'":
+            quote = ch
+        elif source.startswith(closer, i):
+            return i
+        i += 1
+    raise TemplateSyntaxError(f"Unclosed mustache starting near offset {pos}")
+
+
+def _tokenize(source: str) -> list[_Token]:
+    tokens: list[_Token] = []
+    pos = 0
+    while pos < len(source):
+        start = source.find("{{", pos)
+        if start < 0:
+            tokens.append(source[pos:])
+            break
+        if start > pos:
+            if source[start - 1] == "\\":
+                raise TemplateSyntaxError("Escaped mustaches (\\{{) are not supported")
+            tokens.append(source[pos:start])
+        if source.startswith("{{{{", start):
+            raise TemplateSyntaxError("Raw blocks are not supported")
+        m = _TAG_START.match(source, start)
+        assert m is not None
+        open_strip = m.group(1) is not None
+        i = m.end()
+
+        if source.startswith("!--", i):
+            end = re.compile(r"--(~)?\}\}").search(source, i + 3)
+            if end is None:
+                raise TemplateSyntaxError("Unclosed comment")
+            tokens.append(_Tag("comment", "", _Strip(open_strip, end.group(1) is not None)))
+            pos = end.end()
+            continue
+        if source.startswith("!", i):
+            end_idx = source.find("}}", i)
+            if end_idx < 0:
+                raise TemplateSyntaxError("Unclosed comment")
+            text = source[start : end_idx + 2]
+            tokens.append(_Tag("comment", "", _Strip(open_strip, text[-3] == "~")))
+            pos = end_idx + 2
+            continue
+
+        inverse = _INVERSE_RE.match(source, i)
+        if inverse:
+            tokens.append(_Tag("inverse", "", _Strip(open_strip, inverse.group(1) is not None)))
+            pos = inverse.end()
+            continue
+
+        closer = "}}"
+        ch = source[i : i + 1]
+        if source.startswith("#>", i) or source.startswith("#*", i) or ch in (">", "*"):
+            raise TemplateSyntaxError("Partials and decorators are not supported")
+        if ch == "#":
+            kind, i = "open", i + 1
+        elif ch == "/":
+            kind, i = "close", i + 1
+        elif ch == "^":
+            kind, i = "open_inverse", i + 1
+        elif _CHAIN_RE.match(source, i):
+            chain = _CHAIN_RE.match(source, i)
+            assert chain is not None
+            kind, i = "open_chain", chain.end()
+        elif ch == "{":
+            kind, i, closer = "triple", i + 1, "}}}"
+        elif ch == "&":
+            kind, i = "amp", i + 1
+        else:
+            kind = "mustache"
+        end_idx = _find_close(source, i, closer)
+        expr = source[i:end_idx]
+        close_strip = expr.endswith("~")
+        if close_strip:
+            expr = expr[:-1]
+        tokens.append(_Tag(kind, expr.strip(), _Strip(open_strip, close_strip)))
+        pos = end_idx + len(closer)
+    return tokens
+
+
+# ---------------------------------------------------------------------------
+# AST (mirrors the handlebars.js node shapes the whitespace pass looks at)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _Content:
+    original: str
+    value: str
+    left_stripped: bool = False
+    right_stripped: bool = False
+
+
+@dataclass
+class _Mustache:
+    kind: str
+    expr: str
+    strip: _Strip
+
+
+@dataclass
+class _Comment:
+    strip: _Strip
+
+
+@dataclass
+class _Program:
+    body: list[_Node] = field(default_factory=list)
+    chained: bool = False
+
+
+@dataclass
+class _Block:
+    name: str
+    expr: str
+    inverted: bool
+    # Source-order programs, used to emit the pybars source.
+    first: _Program
+    second: _Program | None
+    # handlebars' view after `prepareBlock` swaps inverted blocks; used for whitespace control.
+    program: _Program | None
+    inverse: _Program | None
+    open_strip: _Strip
+    inverse_strip: _Strip | None
+    close_strip: _Strip | None
+
+
+_Node = _Content | _Mustache | _Comment | _Block
+
+
+@dataclass
+class _InverseAndProgram:
+    strip: _Strip
+    program: _Program
+    chain: bool = False
+
+
+def _helper_name(expr: str) -> str:
+    match = re.match(r"[^\s()]+", expr)
+    if not match:
+        raise TemplateSyntaxError("Block is missing a helper name")
+    return match.group(0)
+
+
+class _Parser:
+    def __init__(self, tokens: list[_Token]) -> None:
+        self.tokens = tokens
+        self.pos = 0
+
+    def peek(self) -> _Token | None:
+        return self.tokens[self.pos] if self.pos < len(self.tokens) else None
+
+    def next(self) -> _Token:
+        token = self.tokens[self.pos]
+        self.pos += 1
+        return token
+
+    def parse_root(self) -> _Program:
+        program = self.parse_program()
+        if self.peek() is not None:
+            tag = self.peek()
+            assert isinstance(tag, _Tag)
+            raise TemplateSyntaxError(f"Unexpected {tag.kind} tag {tag.expr!r}")
+        return program
+
+    def parse_program(self) -> _Program:
+        program = _Program()
+        while (token := self.peek()) is not None:
+            if isinstance(token, str):
+                self.next()
+                program.body.append(_Content(token, token))
+                continue
+            if token.kind in ("inverse", "open_chain", "close"):
+                break
+            self.next()
+            if token.kind == "comment":
+                program.body.append(_Comment(token.strip))
+            elif token.kind in ("open", "open_inverse"):
+                program.body.append(self.parse_block(token))
+            else:
+                program.body.append(_Mustache(token.kind, token.expr, token.strip))
+        return program
+
+    def parse_block(self, open_tag: _Tag) -> _Block:
+        program = self.parse_program()
+        inverse_and_program = self.parse_inverse()
+        close = self.next() if self.peek() is not None else None
+        if not isinstance(close, _Tag) or close.kind != "close":
+            raise TemplateSyntaxError(f"Unclosed block {open_tag.expr!r}")
+        name = _helper_name(open_tag.expr)
+        if close.expr != name:
+            raise TemplateSyntaxError(f"{name} doesn't match {close.expr}")
+        return self.prepare_block(open_tag, program, inverse_and_program, close.strip, open_tag.kind == "open_inverse")
+
+    def parse_inverse(self) -> _InverseAndProgram | None:
+        token = self.peek()
+        if not isinstance(token, _Tag):
+            return None
+        if token.kind == "inverse":
+            self.next()
+            return _InverseAndProgram(token.strip, self.parse_program())
+        if token.kind == "open_chain":
+            self.next()
+            program = self.parse_program()
+            nested = self.parse_inverse()
+            # handlebars passes the nested chain as both the inverse and the "close" of the chained block.
+            block = self.prepare_block(token, program, nested, nested.strip if nested else None, False)
+            return _InverseAndProgram(token.strip, _Program([block], chained=True), chain=True)
+        return None
+
+    @staticmethod
+    def prepare_block(
+        open_tag: _Tag,
+        program: _Program,
+        inverse_and_program: _InverseAndProgram | None,
+        close_strip: _Strip | None,
+        inverted: bool,
+    ) -> _Block:
+        inverse: _Program | None = None
+        inverse_strip: _Strip | None = None
+        if inverse_and_program:
+            if inverse_and_program.chain:
+                chained = inverse_and_program.program.body[0]
+                assert isinstance(chained, _Block)
+                chained.close_strip = close_strip
+            inverse_strip = inverse_and_program.strip
+            inverse = inverse_and_program.program
+        hb_program: _Program | None = program
+        hb_inverse = inverse
+        if inverted:
+            hb_program, hb_inverse = inverse, program
+        return _Block(
+            name=_helper_name(open_tag.expr),
+            expr=open_tag.expr,
+            inverted=inverted,
+            first=program,
+            second=inverse,
+            program=hb_program,
+            inverse=hb_inverse,
+            open_strip=open_tag.strip,
+            inverse_strip=inverse_strip,
+            close_strip=close_strip,
+        )
+
+
+# ---------------------------------------------------------------------------
+# WhitespaceControl (port of handlebars/compiler/whitespace-control.js)
+# ---------------------------------------------------------------------------
+
+_PREV_WS = re.compile(r"\r?\n" + JS_WS + r"*?\Z")
+_PREV_WS_ROOT = re.compile(r"(?:^|\r?\n)" + JS_WS + r"*?\Z")
+_NEXT_WS = re.compile(JS_WS + r"*?\r?\n")
+_NEXT_WS_ROOT = re.compile(JS_WS + r"*?(?:\r?\n|\Z)")
+_OMIT_RIGHT = re.compile(r"^[ \t]*\r?\n?")
+_OMIT_RIGHT_MULTI = re.compile("^" + JS_WS + "+")
+_OMIT_LEFT = re.compile(r"[ \t]+\Z")
+_OMIT_LEFT_MULTI = re.compile(JS_WS + r"+\Z")
+
+
+@dataclass
+class _StripInfo:
+    open: bool = False
+    close: bool = False
+    open_standalone: bool = False
+    close_standalone: bool = False
+    inline_standalone: bool = False
+
+
+def _is_prev_whitespace(body: list[_Node], i: int | None = None, is_root: bool = False) -> bool:
+    if i is None:
+        i = len(body)
+    prev = body[i - 1] if i - 1 >= 0 else None
+    sibling = body[i - 2] if i - 2 >= 0 else None
+    if prev is None:
+        return is_root
+    if isinstance(prev, _Content):
+        pattern = _PREV_WS if (sibling is not None or not is_root) else _PREV_WS_ROOT
+        return pattern.search(prev.original) is not None
+    return False
+
+
+def _is_next_whitespace(body: list[_Node], i: int | None = None, is_root: bool = False) -> bool:
+    if i is None:
+        i = -1
+    nxt = body[i + 1] if i + 1 < len(body) else None
+    sibling = body[i + 2] if i + 2 < len(body) else None
+    if nxt is None:
+        return is_root
+    if isinstance(nxt, _Content):
+        pattern = _NEXT_WS if (sibling is not None or not is_root) else _NEXT_WS_ROOT
+        return pattern.match(nxt.original) is not None
+    return False
+
+
+def _omit_right(body: list[_Node], i: int | None = None, multiple: bool = False) -> None:
+    idx = 0 if i is None else i + 1
+    current = body[idx] if idx < len(body) else None
+    if not isinstance(current, _Content) or (not multiple and current.right_stripped):
+        return
+    original = current.value
+    current.value = (_OMIT_RIGHT_MULTI if multiple else _OMIT_RIGHT).sub("", current.value, count=1)
+    current.right_stripped = current.value != original
+
+
+def _omit_left(body: list[_Node], i: int | None = None, multiple: bool = False) -> bool:
+    idx = len(body) - 1 if i is None else i - 1
+    current = body[idx] if idx >= 0 else None
+    if not isinstance(current, _Content) or (not multiple and current.left_stripped):
+        return False
+    original = current.value
+    current.value = (_OMIT_LEFT_MULTI if multiple else _OMIT_LEFT).sub("", current.value, count=1)
+    current.left_stripped = current.value != original
+    return current.left_stripped
+
+
+class _WhitespaceControl:
+    def __init__(self) -> None:
+        self.root_seen = False
+
+    def accept(self, node: _Node | _Program | None) -> _StripInfo | None:
+        if isinstance(node, _Program):
+            self.program(node)
+            return None
+        if isinstance(node, _Block):
+            return self.block(node)
+        if isinstance(node, _Mustache):
+            return _StripInfo(open=node.strip.open, close=node.strip.close)
+        if isinstance(node, _Comment):
+            return _StripInfo(open=node.strip.open, close=node.strip.close, inline_standalone=True)
+        return None
+
+    def program(self, program: _Program) -> None:
+        is_root = not self.root_seen
+        self.root_seen = True
+        body = program.body
+        for i, current in enumerate(body):
+            strip = self.accept(current)
+            if strip is None:
+                continue
+            prev_ws = _is_prev_whitespace(body, i, is_root)
+            next_ws = _is_next_whitespace(body, i, is_root)
+            open_standalone = strip.open_standalone and prev_ws
+            close_standalone = strip.close_standalone and next_ws
+            inline_standalone = strip.inline_standalone and prev_ws and next_ws
+
+            if strip.close:
+                _omit_right(body, i, True)
+            if strip.open:
+                _omit_left(body, i, True)
+            if inline_standalone:
+                _omit_right(body, i)
+                _omit_left(body, i)
+            if open_standalone:
+                assert isinstance(current, _Block)
+                target = current.program or current.inverse
+                assert target is not None
+                _omit_right(target.body)
+                _omit_left(body, i)
+            if close_standalone:
+                assert isinstance(current, _Block)
+                _omit_right(body, i)
+                target = current.inverse or current.program
+                assert target is not None
+                _omit_left(target.body)
+
+    def block(self, block: _Block) -> _StripInfo:
+        self.accept(block.program)
+        self.accept(block.inverse)
+
+        program = block.program or block.inverse
+        assert program is not None
+        inverse = block.inverse if block.program else None
+        first_inverse = last_inverse = inverse
+        if inverse is not None and inverse.chained:
+            chained = inverse.body[0]
+            assert isinstance(chained, _Block) and chained.program is not None
+            first_inverse = chained.program
+            while last_inverse is not None and last_inverse.chained:
+                tail = last_inverse.body[-1]
+                assert isinstance(tail, _Block)
+                last_inverse = tail.program
+
+        close_strip = block.close_strip
+        if close_strip is None:
+            # `block.closeStrip.open` would throw in handlebars.js; only reachable for malformed chains.
+            raise TemplateSyntaxError("Block is missing its close tag")
+        strip = _StripInfo(
+            open=block.open_strip.open,
+            close=close_strip.close,
+            open_standalone=_is_next_whitespace(program.body),
+            close_standalone=_is_prev_whitespace((first_inverse or program).body),
+        )
+
+        if block.open_strip.close:
+            _omit_right(program.body, None, True)
+
+        if inverse is not None:
+            assert first_inverse is not None and last_inverse is not None and block.inverse_strip is not None
+            if block.inverse_strip.open:
+                _omit_left(program.body, None, True)
+            if block.inverse_strip.close:
+                _omit_right(first_inverse.body, None, True)
+            if close_strip.open:
+                _omit_left(last_inverse.body, None, True)
+            if _is_prev_whitespace(program.body) and _is_next_whitespace(first_inverse.body):
+                _omit_left(program.body)
+                _omit_right(first_inverse.body)
+        elif close_strip.open:
+            _omit_left(program.body, None, True)
+
+        return strip
+
+
+# ---------------------------------------------------------------------------
+# Emitting pybars source
+# ---------------------------------------------------------------------------
+
+
+def _emit_program(program: _Program, out: list[str]) -> None:
+    for node in program.body:
+        _emit_node(node, out)
+
+
+def _emit_node(node: _Node, out: list[str]) -> None:
+    if isinstance(node, _Content):
+        out.append(node.value)
+    elif isinstance(node, _Mustache):
+        if node.kind == "triple":
+            out.append("{{{" + node.expr + "}}}")
+        elif node.kind == "amp":
+            out.append("{{&" + node.expr + "}}")
+        else:
+            out.append("{{" + node.expr + "}}")
+    elif isinstance(node, _Block):
+        out.append(("{{^" if node.inverted else "{{#") + node.expr + "}}")
+        _emit_program(node.first, out)
+        if node.second is not None:
+            out.append("{{else}}")
+            # A chained inverse holds a single block, emitted as a nested block.
+            _emit_program(node.second, out)
+        out.append("{{/" + node.name + "}}")
+    # Comments render nothing.
+
+
+def preprocess(source: str) -> str:
+    """Return pybars source whose literal whitespace already matches handlebars.js output."""
+    root = _Parser(_tokenize(source)).parse_root()
+    _WhitespaceControl().accept(root)
+    out: list[str] = []
+    _emit_program(root, out)
+    return "".join(out)
+
+
+# ---------------------------------------------------------------------------
+# Runtime: JS-faithful replacements for pybars globals and built-in helpers
+# ---------------------------------------------------------------------------
+
+_ESCAPE_MAP = {"&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#x27;", "`": "&#x60;", "=": "&#x3D;"}
+_ESCAPE_RE = re.compile("[&<>\"'`=]")
+
+
+def escape_expression(value: object) -> str:
+    """``Handlebars.Utils.escapeExpression``."""
+    if isinstance(value, strlist):
+        return str(value)
+    if value is None:
+        return ""
+    text = js_to_string(value)
+    return _ESCAPE_RE.sub(lambda m: _ESCAPE_MAP[m.group(0)], text)
+
+
+def _prepare(value: object, should_escape: bool) -> Any:
+    if isinstance(value, strlist):
+        return value
+    if should_escape:
+        return escape_expression(value)
+    return "" if value is None else js_to_string(value)
+
+
+def _property(obj: object, name: str) -> Any:
+    if isinstance(obj, Scope):
+        return obj.get(name)
+    if isinstance(obj, Mapping):
+        return obj.get(name)
+    if isinstance(obj, (list, tuple, str)):
+        if name == "length":
+            return len(obj)
+        if name.isdigit() and int(name) < len(obj):
+            return obj[int(name)]
+        return None
+    return None
+
+
+def _resolve(context: Any, *segments: str) -> Any:
+    # Same segment conventions as pybars.resolve ('' = this, '@_parent' = ../), JS property access.
+    if segments == ("",) and isinstance(context, Scope):
+        return context.get("this")
+    carryover = False
+    for segment in segments:
+        if carryover:
+            carryover = False
+            segment = "@" + segment
+        if segment.startswith("@@"):
+            segment = segment[1:]
+            carryover = True
+        if context is None:
+            return None
+        if segment == "":
+            continue
+        context = _property(context, segment)
+    return context
+
+
+def _unwrap(value: Any) -> Any:
+    return value.get("this") if isinstance(value, Scope) else value
+
+
+def _helper_if(this: Any, options: Mapping[str, Any], conditional: Any = None, *rest: Any) -> Any:
+    if rest:
+        raise TemplateSyntaxError("#if requires exactly one argument")
+    conditional = _unwrap(conditional)
+    if not js_truthy(conditional) or hb_is_empty(conditional):
+        return options["inverse"](this)
+    return options["fn"](this)
+
+
+def _helper_unless(this: Any, options: Mapping[str, Any], conditional: Any = None, *rest: Any) -> Any:
+    if rest:
+        raise TemplateSyntaxError("#unless requires exactly one argument")
+    conditional = _unwrap(conditional)
+    if not js_truthy(conditional) or hb_is_empty(conditional):
+        return options["fn"](this)
+    return options["inverse"](this)
+
+
+def _helper_each(this: Any, options: Mapping[str, Any], context: Any = None) -> Any:
+    context = _unwrap(context)
+    result = strlist()
+    items: list[tuple[Any, Any]]
+    if isinstance(context, (list, tuple)):
+        items = list(enumerate(context))
+    elif isinstance(context, Mapping):
+        lookup = {(k if isinstance(k, str) else js_to_string(k)): v for k, v in context.items()}
+        items = [(key, lookup[key]) for key in js_object_keys(context)]
+    else:
+        items = []
+    if not items:
+        return options["inverse"](this)
+    last = len(items) - 1
+    for index, (key, value) in enumerate(items):
+        scope = Scope(value, this, options["root"], index=index, key=key, first=index == 0, last=index == last)
+        result.grow(options["fn"](scope))
+    return result
+
+
+def _helper_missing(this: Any, name: str, *args: Any) -> Any:
+    if not args:
+        return None
+    raise TemplateSyntaxError(f'Missing helper: "{name}"')
+
+
+def _block_helper_missing(this: Any, options: Mapping[str, Any], context: Any) -> Any:
+    # Blocks named after a data property ({{#prop}}): handlebars' blockHelperMissing.
+    if context is True:
+        return options["fn"](this)
+    if context is False or context is None:
+        return options["inverse"](this)
+    if isinstance(context, (list, tuple)):
+        return _helper_each(this, options, context) if context else options["inverse"](this)
+    return options["fn"](context)
+
+
+# ---------------------------------------------------------------------------
+# Custom helpers registered by upstream render.ts
+# ---------------------------------------------------------------------------
+
+
+def _helper_eq(this: Any, a: Any = None, b: Any = None, *_: Any) -> bool:
+    return js_strict_equals(_unwrap(a), _unwrap(b))
+
+
+def _helper_includes(this: Any, array: Any = None, value: Any = None, *_: Any) -> bool:
+    array, value = _unwrap(array), _unwrap(value)
+    if not isinstance(array, (list, tuple)):
+        return False
+    return any(js_same_value_zero(item, value) for item in array)
+
+
+def _require_str(value: Any, helper: str) -> str:
+    if not isinstance(value, str):
+        # JS would throw calling String.prototype.replace on a non-string.
+        raise TypeError(f"{helper}: expected a string, got {js_to_string(value)!r}")
+    return value
+
+
+def _non_alnum_to_underscore(value: str) -> str:
+    # JS regexes replace per UTF-16 code unit, so astral characters become two underscores.
+    return "".join(c if c.isascii() and c.isalnum() else "_" * utf16_len(c) for c in value)
+
+
+def _helper_snake_case(this: Any, value: Any = None, *_: Any) -> str:
+    return _non_alnum_to_underscore(_require_str(_unwrap(value), "snakeCase")).lower()
+
+
+def _helper_path_slug(this: Any, value: Any = None, *_: Any) -> str:
+    slug = _non_alnum_to_underscore(_require_str(_unwrap(value), "pathSlug"))
+    return re.sub(r"_+", "_", slug.lstrip("_")).lower()
+
+
+def _helper_safe_json(this: Any, value: Any = None, *_: Any) -> SafeString:
+    text = json_stringify(_unwrap(value))
+    return SafeString("undefined" if text is None else text)
+
+
+def _helper_py_json_str(this: Any, value: Any = None, *_: Any) -> SafeString:
+    text = json_stringify(_unwrap(value))
+    return SafeString("undefined" if text is None else (json_stringify(text) or ""))
+
+
+def _helper_escape_py_str(this: Any, value: Any = None, *_: Any) -> SafeString:
+    value = _unwrap(value)
+    text = value if isinstance(value, str) else ""
+    return SafeString(text.replace("\\", "\\\\").replace('"""', '\\"\\"\\"'))
+
+
+def _helper_some(this: Any, array: Any = None, key: Any = None, *_: Any) -> bool:
+    array = _unwrap(array)
+    if not isinstance(array, (list, tuple)):
+        return False
+    key = _unwrap(key)
+    return any(isinstance(item, Mapping) and key in item and js_truthy(item[key]) for item in array)
+
+
+def _helper_or(this: Any, *args: Any) -> bool:
+    return any(js_truthy(_unwrap(arg)) for arg in args)
+
+
+HELPERS: dict[str, Callable[..., Any]] = {
+    "if": _helper_if,
+    "unless": _helper_unless,
+    "each": _helper_each,
+    "helperMissing": _helper_missing,
+    "blockHelperMissing": _block_helper_missing,
+    "eq": _helper_eq,
+    "includes": _helper_includes,
+    "snakeCase": _helper_snake_case,
+    "pathSlug": _helper_path_slug,
+    "safeJson": _helper_safe_json,
+    "pyJsonStr": _helper_py_json_str,
+    "escapePyStr": _helper_escape_py_str,
+    "some": _helper_some,
+    "or": _helper_or,
+}
+
+
+# ---------------------------------------------------------------------------
+# Compilation
+# ---------------------------------------------------------------------------
+
+
+class _Compiler(pybars.Compiler):
+    def whitespace_control(self, source: str) -> str:
+        # Whitespace was already resolved by `preprocess`.
+        return source
+
+
+# pybars' code builder is class-level state, so compilation is serialized.
+_COMPILE_LOCK = threading.Lock()
+
+Template = Callable[[Mapping[str, Any]], str]
+
+
+@lru_cache(maxsize=512)
+def compile_template(source: str) -> Template:
+    """Compile Handlebars ``source`` into a function rendering a data mapping to a string."""
+    pybars_source = preprocess(source)
+    with _COMPILE_LOCK:
+        code = _Compiler()._generate_code(pybars_source).full_code
+    namespace: dict[str, Any] = {}
+    exec(compile(code, "<handlebars-template>", "exec"), namespace)  # noqa: S102 - pybars-generated code
+    namespace["prepare"] = _prepare
+    namespace["resolve"] = _resolve
+    render = namespace["render"]
+
+    def template(data: Mapping[str, Any]) -> str:
+        return str(render(data, helpers=HELPERS))
+
+    return template
+
+
+def render_template(source: str, data: Mapping[str, Any]) -> str:
+    return compile_template(source)(data)