Setup#

Setup: load the templates once and build the Engine.

Setup describes where the templates are and how to render and sign them. Setup.run() validates the root and the signing keys, loads and parses every .html file under root and returns the Engine that Page, Fragment and Stream render with.

from anza import Setup, SignOptions

engine = Setup(
    root="./templates",
    signing=SignOptions(mode="hmac", secret=secret),  # 32+ bytes
    fragments=["feed/", "partials/menu.html"],        # fragment allowlist
    escape=True,                                       # escape {{x}}, keep {{{x}}} raw
    max_template_bytes=512 * 1024,                     # default 1 MiB
    watch=True,                                        # reload on change
).run()

engine.close()  # stops the watcher

Template layout

Templates are named by their path relative to root, with / separators: pages/home.html, layout/shell.html, feed/card.html.

  • pages/ holds the page templates Page resolves routes to (/ is pages/home.html, pages/index.html is the catch-all).

  • layout/shell.html is the optional document every page goes into, as {{content}}.

  • Any other template can be rendered as a fragment, unless fragments limits them.

A template name is a relative path: not empty, no leading /, no \ or NUL, and no empty, . or .. segment. A malformed name is a VALIDATION error. Lookups only use the templates loaded at setup: a cache miss is NOT_FOUND and request input never reaches the filesystem.

Options

  • fragments limits which templates a fragment can render. An entry ending in / allows that prefix, any other entry that exact name. Anything else is reported as Template '<name>' not found. Empty (the default) allows every template.

  • escape HTML-escapes {{slot}} values; {{{slot}}} stays raw. Off by default: values are inserted as is.

  • max_template_bytes makes a larger file a TEMPLATE error at load.

  • watch=True starts a polling thread that reloads the templates when .html files are added, changed or removed. Stop it with Engine.close().

  • signing takes SignOptions; see Signing & verification.