Cheat sheet

The whole of Bretzel condensed onto one page. Ctrl-F what you need.

What one types — the package's surface

Grouped by the need each name answers, not by its Python nature. A helper callable from a handler has exactly one access point: this one.

mount the application5

Name	Nature	What it does
Bretzel	class	The Bretzel application instance.
BretzelConfig	class	The resolved, validated configuration of a :class:`Bretzel` app.
Feature	class	One feature's contract. Declared once per feature package ::
PWA	class	Declare the metadata that makes an application installable.
PWAIcon	class	Describe one icon in the web application manifest.

declare a route5

Name	Nature	What it does
download	function	Mark a function as the producer for a file served at ``GET path``.
error_page	decorator	Mark a function as the custom page for an HTTP status code.
layout	decorator	Mark a function as a layout. Free decorator — needs no app.
page	decorator	Mark ``fn`` as the handler for ``GET path`` (or other methods).
refreshable	decorator	Wrap ``fn`` as a refreshable page region.

act from a handler7

Name	Nature	What it does
abort	function	Raise an HTTP error from inside a request handler.
background	decorator	Mark ``fn`` as an after-response background task.
idempotent	decorator	Mark a handler idempotent for ``ttl`` seconds.
push_url	function	Change the displayed URL without navigating or reloading the page.
redirect	function	Navigate the browser to ``url`` after the current request.
refresh	function	Force a refresh of a zone — the single imperative trigger.
reload	function	Reload the page displayed by the browser after the current request.

act in the browser5

Name	Nature	What it does
copy	function	Copy ``value`` to the clipboard when the action runs.
fullscreen	function	Enter fullscreen mode when the action runs.
print_page	function	Open the browser print dialog when the action runs.
share	function	Open the native share sheet, or copy the URL when sharing is unavailable.
vibrate	function	Vibrate the device when the action runs.

render5

Name	Nature	What it does
ColorScheme	class	Framework-owned color mode (singleton via the ``default`` key).
Language	class	Read or select the language for the current request.
LiveConnection	class	Expose the state of the framework's real-time connection.
Screen	class	Per-request viewport shape read from the ``bz_screen`` cookie.
ui	value	Lowercased aliases for the shipped components.

declare state1

Name	Nature	What it does
state	module	Typed state for Bretzel applications.

identify the current user2

Name	Nature	What it does
auth	module	Authentication helpers for Bretzel applications.
oauth	module	OAuth and OpenID Connect authentication providers.

handle an error3

Name	Nature	What it does
AuthRequiredError	class	Raised when a ``user``-scoped state is resolved with no user.
BretzelError	class	Generic runtime error from Bretzel internals.
FeatureError	class	Raised when a feature contract is malformed, or a set of features

package metadata1

Name	Nature	What it does
__version__	value	'0.1.0a2'

State — server (4 scopes)

from bretzel.state import PageState, SessionState, UserState, AppState
from bretzel.state import field, validator, computed

class Cart(SessionState):          # page / session / user / app
    items: list[dict] = field(default_factory=list)
    coupon: str = ""

    @validator("coupon")           # receives (self, value), RETURNS the value
    def _norm(self, v: str) -> str:
        return v.strip().upper()

    @computed                       # derived, auto-tracked
    def total(self) -> float:
        return sum(i["price"] for i in self.items)

State — client (3 persistence modes)

from bretzel.state import ClientState

class FilterUI(ClientState, persist="local"):
    #  "memory"  → throwaway (lost on reload)
    #  "session" → survives a reload, not a close
    #  "local"   → survives everything
    sort_by: str = "date"

Actions — server vs client

# Server: on_click = callable → hx-post, HMAC signed
def save() -> None:
    Cart().coupon = ""          # mutation → automatic re-render
ui.button("Save", on_click=save)

# Client: on_click = an expression (string) → no round trip
ui.button("Top", on_click="window.scrollTo(0, 0)")

# Imperative: the method RETURNS the client string
with ui.dialog() as d:
    ui.text("Are you sure?")
ui.button("Open", on_click=d.open())

# Binding: driving a ClientState
panel = PanelUI()
ui.button("Toggle", on_click=panel.open.toggle())

Reactivity — mutate → re-render

from bretzel import refreshable, ui

@refreshable(deps=[Cart])          # declarative: re-render when Cart changes
def cart_view() -> None:
    for it in ui.each(Cart().items, key="id"):
        ui.text(it["label"])

from bretzel import refresh
refresh(cart_view)                 # imperative, from a handler
# refresh on a broadcast=[…] zone → SSE fan-out to the other tabs

⚠️ Trap no. 1

Every file declaring a State MUST start with `from __future__ import annotations` (PEP 649) — otherwise the fields do not register, silently.

from __future__ import annotations   # ← FIRST, always

The other traps:Traps →