{"version":"v1.0","client_state":{"DocsNavigation.default":{"fields":{"query":""},"persist":"memory","send_to_server":true},"ColorScheme.default":{"fields":{"mode":"system"},"persist":"local","send_to_server":true},"Selection.default":{"fields":{"picked":"bretzel"},"persist":"memory","send_to_server":true}},"endpoints":{"action":"/_bretzel/action","sse":"/_bretzel/sse","refetch":"/_bretzel/refetch"},"csrf":"66cd954a496c96a84bffbd9795018f3d","page_id":"b8b6b39503be4ab5be1b96cac2c42413","address":""}

The framework's tree

118 packages, read live. This page writes no name and no description: it calls `describe_package('bretzel')` and renders what comes back. A folder added tomorrow appears here without anyone touching this file.
Two levels, and they complement each other
The folders marked “classified” ALSO have a table grouping their symbols by need — that is what `bretzel describe bretzel.state` returns. The others only have their arrangement, which is already the answer to “what is in there”.

The layout

  • bretzelclassified
    • coreclassified
    • probeclassified
    • runtimeclassified
    • themeclassified

What the folder says about itself

bretzelBretzel — Server-Driven UI for Python.
bretzel.cliLayer 7 — the CLI. See bretzel.cli.main.Layer 7 — the CLI. See bretzel.cli.main. The CLI creates and runs the minimal public skeleton, describes the framework, judges application code and drives an app in a browser.1 module(s), 2 public symbol(s)
main.pyCreate, run, describe, check, and probe a Bretzel application.
build_parser (function) main (function)
bretzel.cli.commandsCLI subcommands.1 module(s), 2 public symbol(s)
project.pyCreate and run the smallest complete Bretzel application.
create_project Create a self-contained starter project and return the written files. run_project Import a Bretzel app and run it with development defaults.
bretzel.componentsUser-facing components exposed through the ui namespace.1 module(s), 1 public symbol(s)
color_shapes.pyWhat the component themes know and the Tailwind scanner does not.
dynamic_responsive_classes Return responsive classes that a graduated property may emit.
bretzel.components.actionsButtons and links.1 module(s), 5 public symbol(s)
_wiring.pyThe loading= wiring shared by Button and IconButton.
build_loading_spinner The button's spinner, built in __init__. apply_loading_disabled bz-attr:disabled = (loading) || (disabled). loading_leading_children The spinner ↔ leading icon mutex, in the children's order. anchor_tag An href makes an action an ANCHOR — ui.button and ui.icon_button alike, one rule for both. finish_anchor What changes once an action renders as an <a>.
bretzel.components.actions.buttonRe-export the Button component.2 module(s), 1 public symbol(s)
button.pyButton — Archetype 3 action component.
Button Action button with variant / size / color theming + named slots.
theme.pyDefault Button theme.
bretzel.components.actions.icon_buttonicon_button component.2 module(s), 1 public symbol(s)
icon_button.pyIconButton — square button whose only content is an icon.
IconButton Icon-only button. Pass the icon name positionally + an aria_label for screen readers.
theme.pyDefault IconButton theme.
bretzel.components.actions.linklink component.2 module(s), 1 public symbol(s)
link.pyLink — anchor with three visual variants and a11y disabled state.
Link Anchor element with semantic colour, three variants (hover / underline / text), and a11y-correct disabled state.
theme.pyDefault Link theme.
bretzel.components.baseComponent authoring primitives — public API of the base layer.Component authoring primitives — public API of the base layer. Component authors import from here :: from bretzel.components.base import Component, reactive_prop, el Anything not re-exported is internal to the framework.9 module(s), 81 public symbol(s)
_wiring.pyThe shared base-layer wiring — two jobs, not one.
register_sticky_bar Register a sticky bar for the placement pass. check_sticky_bar_placement Judge the placement of sticky bars once the tree is built. wire_sidebar_triggers Give each ui.sidebar_trigger the bar it drives. check_sidebars_are_reachable A bar that can disappear must have a way back. refuse_a_value_off_the_table size= / variant= outside the table: raise, instead of keeping quiet. declared_steps The steps of a sizes / variants table, THREE shapes. theme_context (theme, slots, sizes, size, color) — render()'s preamble. color_bridge_class The bridge class to set on the root, or None. unwrap_transparent (the real child, what gives it back its wrapper). drop_tag_bound_attrs Remove from attrs what no longer means anything under tag. trigger_hugs_its_content Does the root size itself to its content? trigger_is_full_width True if any trigger fills its row. expand_fit_wrapper Collapse an anchored overlay's inline-* w-fit h-fit default to block w-full. Strip the fit tokens too : Tailwind's w-full w-fit ordering is non-deterministic, so leaving w-fit in can still win and the full-width trigger collapses. shrink_fit_wrapper The other direction : a w-full root that must hug its trigger. trigger_asks_full_width Does anything ask this wrapper to fill its row ? show_attrs data-open state for CSS-driven enter/leave animations. focus_trap_effect Panel bz-effect : trap focus while open, restore on close. modal_root_effect Root bz-effect (modal overlays) : scroll lock + dispatch. dispatch_root_effect Root bz-effect (anchored overlays) : open/close dispatch only. changed_since_open_effect bz-effect: has the value moved since it was opened? floating_placement Theme position + align → a $bz.helpers.floating placement. anchored_panel_effect Panel bz-effect for anchored overlays. anchored_trigger_wrapper Wrap a caller-supplied trigger for an anchored overlay. anchored_dismiss_init Root bz-init for anchored overlays : Escape + click-outside. imperative_listeners bz-on:bz-open/close/toggle — the imperative-API receivers. install_open_close_toggle Install the write-only imperative API .open() / .close() / .toggle() as INSTANCE ATTRIBUTES on component. install_value_commands Install .set() / .clear() / .focus() / .blur(). close_handler_wired True if a close handler is wired on attrs — server (hx-trigger="close") or client (bz-on:close). dismiss_local_scope The dismiss's client-local scope: bz-data="{open: true}" + bz-show="open" to set on the root. Keyed by bz-id; no FOUC pre-stamp (the initial open: true eval is truthy). Shared by Alert / Badge / Banner. dismiss_button The × button — ONE emission for the whole framework. teleport_to_body Wrap an overlay panel in a <template bz-teleport="body"> so the runtime projects it under <body> at init. calendar_value_mirror bz-effect body mirroring value_expr onto a child <bz-calendar>'s observed value ATTRIBUTE. change_emit_effect bz-effect body that fires change on a hidden input. trigger_event The EVENT hx-trigger serves, without its modifiers. retrigger Rename an hx-trigger's event while KEEPING its modifiers. pop_change_handler Pop every change-handler attribute out of attrs (in place). hidden_carrier_attrs The SKELETON of a value-carrying <input type="hidden">. relocate_server_action Route the server-action bundle to the right target, in place. activate_keydown Enter / Space activate a NON-native element. reject_sealed A SEALED prop passed at the call: we say so, with a sentence. coerce_index The SSR value of a driven index — best effort, never an exception. bool_attr A reactive attribute that must carry the STRING "true"/"false". server_sync_marker _serverSync fragment for a component's bz-data object literal. scope_literal The bz-data object literal of a component with a runtime slab. escape_init bz-init : global Escape-to-close while the overlay is open. outlet_target_attrs {"hx-target": "#outlet_<shell>"} for a link that names its region.
attrs.pyKwargs splitting + attribute-name normalisation.
is_declared_raw_attr True when the kwarg is a declared raw HTML escape hatch. ComponentDefinitionError Raised at class creation time when a component is malformed (e.g. EVENTS lists an event with no matching on_<event> parameter in __init__). ComponentUsageError Raised at instantiation time when the user mis-uses a component (unknown slot, event handler for an event that isn't supported). normalize_attr_name Convert a Python-friendly kwarg name to an HTML attribute name. is_passthrough_attr True when the kwarg is a raw HTMX attribute that should pass through to the rendered element verbatim. reject_dead_alpine_attr Raise when name carries an Alpine directive prefix. split_kwargs Carve kwargs into the five buckets the Component constructor consumes.
binding_discipline.pyType discipline for reactive_prop bindings.
is_scalar_type True when the annotation resolves to a scalar (or a union of scalars / None). Optional/Union with at least one non-scalar arm is treated as non-scalar. validate_scalar_binding Raise ComponentUsageError when binding.value is a list / dict / tuple / set while the prop's declared type is scalar.
component.pyComponent — the single base class apps and component authors subclass.
merge_attr Set value on attrs[name] per the precedence contract. Component Base class for every Bretzel component. stamp_display_none Append display:none to an attrs dict's inline style. coerce_children Normalise what a render= escape hatch returned, into children. reject_component Refuse a Component on a parameter that is NOT a slot. finish_render The three passes EVERY component node must undergo after its render(), in order. el Tiny ergonomic wrapper around bretzel.core.tree.Element.
events.pyEvent handler dispatch for components (V3 wire).
HandlerError Raised when a component receives an event handler that the framework can't address (lambda, closure, non-callable / non-str) or can't emit (two server handlers on one element). cross_check_events Verify that every event in cls.EVENTS has a matching on_<event> parameter in cls.__init__. encode_handler_id Return the addressable id for handler. client_event_attr Attribute name for a client-only handler : bz-on:<event>. action_attrs HTMX attribute set for one server-handled event (V3 wire). item_action_attrs Route an on_* set on an INTERNAL ELEMENT, not on the root. pending Return a client expression indicating whether an action is in flight.
reactive_prop.pyReactive props — the bridge between component kwargs and runtime attrs.
ReactivePropDescriptor Class-level descriptor for a reactive prop. reactive_prop Declare a reactive prop on a Component subclass. reads_as_client_expr The whole question: is value, set on THIS prop, code? looks_like_client_expr Heuristic: does value look like a client / JS expression?
responsive.pyResponsive prop values — one {breakpoint: value} dialect, one parser.
responsive_classes Resolve value to a class string, honouring a breakpoint dict. looks_like_a_breakpoint_dict Is this dict a scale of steps, or DATA? reject_stray_breakpoints A step dict on a prop that is not graded: we SAY so.
sizes.pyThe size scale, and how a sizes table is read.
is_size_keyed Is the table indexed by SIZE (and not by slot)? size_vocabulary The values size= can take for this component theme. icon_size_for The icon size that goes with this label — None when its text class is not in ICON_SIZE_ABOVE.
testing.pyTest-only helpers for component authors.
render_isolated Open an isolated render context for unit tests. panel_from_teleport Return an anchored overlay's panel from its teleport wrapper.
bretzel.components.chartsTier 8 — data visualisation.Tier 8 — data visualisation. Server-rendered SVG charts. No external JS library is loaded — hover tooltips and legend toggles ride $bz.charts.* scope factories declared via bz-data on the chart wrapper. These are LIVE : the runtime slab bretzel/runtime/_src/10_charts.js ships tooltipScope / lineScope / scatterScope and the chart components wire them (bz-data="$bz.charts.tooltipScope()" + per-mark bz-on:mouseenter). Public surface : - Sparkline — inline trend indicator (single series, no axes). - BarChart — categorical bars, single or multi-series. - LineChart — continuous line, single or multi-series. - PieChart — pie / donut. - ScatterChart — continuous X/Y dots, independent series. - Series — light dataclass for multi-series payloads. - Reference — horizontal threshold line annotation. Optimised for 10 – 1 000 points per chart. Beyond that range, SVG becomes the bottleneck (one DOM node per point) ; a Canvas-backed variant (uPlot or similar) would land as a separate component family when a concrete need arrives.4 module(s), 21 public symbol(s)
_layers.pySVG layers shared by the charts — the pieces that build Element.
reject_empty_text_component empty_text= is not a slot — the four charts refuse it. render_empty_state A chart's empty state: a ui.empty_state in a box the size of the plot, or the escape hatch the author placed. render_axis_layer The vertical axis: the axis line, the horizontal gridlines, the tick labels. plot_svg The <svg> of a series chart — which IS its plot rectangle. apply_fixed_width width=N: the chart is N pixels wide, never wider than its container. Without it, it fills the container. render_static_legend The non-interactive legend: one dot + one label per entry.
_svg.pyShared SVG primitives for the chart components.
format_value Format a numeric value for axis ticks, bar labels, tooltips. linear_scale Return a function mapping domain_* linearly into range_*. nice_domain Pick a (min, max) that frames values with a small visual pad. compute_ticks Return target_count-ish "nice" tick values BRACKETING the domain. The first and last ticks fall on round numbers that extend *past* domain_min / domain_max — callers typically use these endpoints as the chart's visible y-range so the axis line spans full ticks and the visual bottom isn't a half-step above the smallest data point (which created the "gridline starts at 60 even though data goes down to 45" surprise). text_width Estimated rendered width of label at font_px, in pixels. axis_margin The room left of the plot for right-aligned axis labels. line_path SVG d attribute for a polyline through points. smooth_path SVG d for a Catmull-Rom-as-Bézier curve through points. area_path Closed path filling the region between points and baseline_y. arc_path SVG path for a pie wedge (inner_radius=0) or donut wedge.
reference.pyReference dataclass — horizontal threshold line + label.
Reference One reference line on a chart's y axis.
series.pyLight Series dataclass for multi-series chart payloads.
Series One data series in a multi-series chart. to_timestamp Convert a date / datetime / number to a POSIX timestamp. coerce_xy_series Normalise a chart's data= into list[Series] of (x, y). coloured_slot A chart slot's class, PLUS its colour's bridge.
bretzel.components.charts.bar_chartbar_chart component.2 module(s), 1 public symbol(s)
bar_chart.pyBarChart — categorical bars, single or multi-series.
BarChart Categorical bar chart.
theme.pyDefault BarChart theme.
bretzel.components.charts.line_chartline_chart component.2 module(s), 3 public symbol(s)
line_chart.pyLineChart — continuous x, single or multi-series.
LineChart Continuous-x line chart with crosshair hover. as_date_formatter Make a time-axis formatter receive a datetime. resolve_date_axis_format The effective x-axis formatter, and whether the axis is temporal.
theme.pyDefault LineChart theme.
bretzel.components.charts.pie_chartpie_chart component.2 module(s), 1 public symbol(s)
pie_chart.pyPieChart — pie or donut, optional arc labels + centre text.
PieChart Pie or donut chart.
theme.pyDefault PieChart theme.
bretzel.components.charts.scatter_chartscatter_chart component.2 module(s), 1 public symbol(s)
scatter_chart.pyScatterChart — continuous X / Y dots, no connecting line.
ScatterChart Continuous-X-Y scatter plot.
theme.pyDefault ScatterChart theme.
bretzel.components.charts.sparklinesparkline component.2 module(s), 1 public symbol(s)
sparkline.pySparkline — inline single-series trend indicator.
Sparkline Inline single-series trend indicator.
theme.pyDefault Sparkline theme.
bretzel.components.dataStructured data display.
bretzel.components.data.accordionaccordion component.2 module(s), 2 public symbol(s)
accordion.pyAccordion / AccordionItem — collapsible content panels.
Accordion Stack of collapsible AccordionItem panels. AccordionItem One collapsible row inside an Accordion.
theme.pyDefault Accordion / AccordionItem theme.
bretzel.components.data.datatableDatatable — public surface of the datatable package.Datatable — public surface of the datatable package. bretzel.state.Query comes out through this door, the same as bretzel.components.Move — the type an app handler must name to write its signature (def load(q: Query)). It travels with apply_query, which belongs to the component: five of the repository's six call sites import them on the same line. bretzel.state.datatable.DatatableState comes out here too, and it is deliberate: writing a table asks for the component, its state, Query and apply_query, and it is ONE task. The FILE, for its part, moved down into bretzel/state/datatable/ on 2026-08-29 — it depended on nothing of this layer — but moving a file is not moving a door. It came out of from bretzel import DatatableState, on the top floor, where it was the only component state.2 module(s), 9 public symbol(s)
datatable.pyDatatable — a bretzel.components.data.table.Table that sorts, pages and searches.
decode_export Inverse of _encode_export, for the route. sort_by Advance the sort on key — bound per column by the header button. go_to_page Move to the page the pager just submitted. search_for Apply the search box's current text, and go back to page 1. apply_filter Commit one column's selection — fired when its panel CLOSES. clear_filters Drop every column filter — the toolbar's reset. column_domain Every distinct value column key takes across rows, sorted. apply_query Run query over rows : filter → search → sort → page. Datatable Table with server-driven sort, pagination and search.
theme.pyDefault Datatable theme.
bretzel.components.data.diagramDiagram — a directed graph laid out in layers, rendered server-side.3 module(s), 15 public symbol(s)
diagram.pyDiagram — a directed graph, laid out in layers on the server.
GraphNode Describe one node in a graph. GraphEdge Describe a directed edge from source to target. node Describe a graph node for ui.diagram. edge Describe a graph edge for ui.diagram. Diagram Render a server-laid-out directed graph in layers.
layout.pyLayered layout of a directed graph — pure, with no rendering.
Metrics The layout's distances, in pixels. Box A placed node — top-left corner, plus its effective size. Route A placed edge. Placement What the engine returns, and all it returns. break_cycles (acyclic edges, reversed edges). assign_layers {key: layer index} — longest path from the roots. order_layers Order each layer so as to reduce the crossings. layout Lay out a directed graph. neighbourhood focus plus what it touches, at depth hops, both ways. keys_from_edges The set of cited nodes, in order of first appearance.
theme.pyDefault theme for Diagram.
bretzel.components.data.tabletable component.2 module(s), 4 public symbol(s)
table.pyTable — simple data table with custom cell renderers.
Column Describes one column of a Table or Datatable. column Build a Column — sugar so users can do ui.column(...) instead of importing the dataclass. read_cell Look up key on row — the one row-access rule. Table Simple data table — header row + body rows, styled by theme.
theme.pyDefault Table theme.
bretzel.components.data.treetree component.2 module(s), 2 public symbol(s)
theme.pyDefault Tree / TreeNode theme.
tree.pyTree / TreeNode — a recursive, collapsible hierarchy.
Tree Root of a collapsible hierarchy of TreeNode\s. TreeNode One node inside a Tree.
bretzel.components.feedbackUser feedback (alert, notification, progress, etc.).
bretzel.components.feedback.alertalert component.2 module(s), 1 public symbol(s)
alert.pyAlert — inline status panel.
Alert Status panel : leading icon, optional title, message body, optional dismiss button on the right.
theme.pyDefault Alert theme.
bretzel.components.feedback.avataravatar component.2 module(s), 2 public symbol(s)
avatar.pyAvatar — round / square user image with initials fallback.
initials_of A name's initials — "Jean Hoccart" → "JH". Avatar Round / square user chip with image or initials fallback.
theme.pyDefault Avatar theme.
bretzel.components.feedback.badgebadge component.2 module(s), 1 public symbol(s)
badge.pyBadge — small inline label / status / count pill.
Badge Inline pill — count / status / tag / filter chip.
theme.pyDefault Badge theme.
bretzel.components.feedback.bannerbanner component.2 module(s), 1 public symbol(s)
banner.pyBanner — full-width page-level status strip.
Banner Full-width page-level status strip.
theme.pyDefault Banner theme.
bretzel.components.feedback.empty_stateempty_state component.2 module(s), 1 public symbol(s)
empty_state.pyEmptyState — "nothing here yet" placeholder.
EmptyState Centred placeholder for "nothing here yet" surfaces.
theme.pyDefault EmptyState theme.
bretzel.components.feedback.notificationui.notification toast helper.2 module(s), 4 public symbol(s)
notification.pyui.notification — toast helper, V1 idiom.
notification Queue a toast to fire at end-of-request. skeleton_html Build the empty toaster skeleton injected into <body> once per page render. serialise_pending Render the pending toast queue into a <bz-patch> block (V3).
theme.pyDefault theme for the ui.notification toast helper.
runtime_payload Return the theme dict in the exact shape the runtime JS expects.
bretzel.components.feedback.progressprogress component.2 module(s), 1 public symbol(s)
progress.pyProgress — horizontal value indicator.
Progress Horizontal progress bar.
theme.pyDefault Progress theme.
bretzel.components.feedback.skeletonskeleton component.2 module(s), 1 public symbol(s)
skeleton.pySkeleton — loading placeholder block.
Skeleton Loading-placeholder block.
theme.pyDefault Skeleton theme.
bretzel.components.inputsUser input components.4 module(s), 28 public symbol(s)
_checkable.pyThe shared render of the two checkable controls — Checkbox and Switch.
render_checkable <label>: the real <input>, the fake visuals, then the label. sized_slot A visual slot's composed class, plus its size entry.
_picker.pyShared surface of the panel pickers — Select and Combobox.
sized_slot Compose slots[slot] + sizes[<size>][slot] into one string. badge_pill_classes Compose the (pill_class, close_class) strings from BADGE_THEME for use inside a pill-rendering bz-for template. Single source of truth for pill styling : Combobox / Select multi-pickers both delegate here so a Badge theme tweak propagates everywhere automatically. normalise_option Return (value, label, disabled) for any of the accepted option shapes : str / tuple / dict. option_body The BODY of an option — what render= replaces. has_picks SSR snapshot: does the picker have a selection at the first paint? render_x_icon The clear button's × glyph, at the picker's size. option_check The tick of a PICKED option, in multi mode. build_pills_template Reactive pills via <template bz-for>. Each picked value renders as <span class="pill">label <button>×</button></span>. build_header_bar The panel's sticky header — three zones in one flex row.
_picker_field.pyThe shared mechanics of the *picker fields* — editable field + popover.
value_expr The expression the DIRECTIVES read for the field's value. relocate_field_events Empty the root of its handlers, towards the carrier that can fire them. detach_wrapper_carriers Remove from the root what makes no sense there, and return the name. hidden_carrier The <input type=hidden> that carries the value in the form data. calendar_picker_scope The bz-data of a picker whose panel is a <bz-calendar>. panel_calendar The panel's <bz-calendar> — detached, but ADDRESSED by its picker. icon_button One of the frame's two buttons: the × or the panel opener. trigger_button The button that toggles the panel. clear_button The × — visible only when there is a value to clear. anchored_panel The popover: anchored by $bz.helpers.floating, closed at SSR. render_calendar_field The WHOLE render of a picker with a <bz-calendar> panel.
_wiring.pyShared V3 client wiring for input components.
add_local_value_scope Give an INTERACTIVE, LOCAL simple input an internal value scope. force_boolean_form_vals Make a server-bound checkbox/switch always transmit its boolean. false_companion_input The other half of "an unticked box still sends its false". value_command_listeners bz-on:bz-set for $el.value carriers. checked_command_listeners bz-on:bz-toggle / bz-on:bz-set for $el.checked toggles. date_to_iso Coerce a date-ish prop value to an ISO YYYY-MM-DD string.
bretzel.components.inputs.calendarRe-export the Calendar component and its helpers.2 module(s), 5 public symbol(s)
calendar.pyCalendar — month-grid date picker, single or range.
compute_month_grid Return 6 rows × 7 cells covering the displayed month. format_month_label "<MonthName> <Year>" (e.g. "March 2026"). rotate_weekday_names Return the 7 weekday names rotated so weekstart comes first. normalise_marks marks= → {"2026-08-14": 3}, in both of its call shapes. Calendar Month-grid date picker, single or range. Web Component-backed.
theme.pyDefault Calendar theme.
bretzel.components.inputs.checkboxcheckbox component.2 module(s), 1 public symbol(s)
checkbox.pyCheckbox — boolean input with a styled "soft-tick" box.
Checkbox Boolean toggle input with optional inline label.
theme.pyDefault Checkbox theme.
bretzel.components.inputs.color_pickerColorPicker — a colour field with a swatch panel.2 module(s), 2 public symbol(s)
color_picker.pyColorPicker — colour field with a swatch panel.
hex_or_empty Coerce a colour value to "#rrggbb" or "". ColorPicker Render a color field with a swatch selection panel.
theme.pyDefault ColorPicker theme.
bretzel.components.inputs.comboboxcombobox component.2 module(s), 1 public symbol(s)
combobox.pyCombobox — search-as-you-type select with optional multi-pick.
Combobox Search-as-you-type select with single / multi modes.
theme.pyDefault Combobox theme.
bretzel.components.inputs.date_pickerRe-export the DatePicker component.2 module(s), 2 public symbol(s)
date_picker.pyDatePicker — single-date input with an inline calendar popover.
normalise_to_iso_js The free-form → ISO blur normaliser for value_expr. DatePicker Single-date input with an inline calendar popover.
theme.pyDefault DatePicker theme.
bretzel.components.inputs.date_range_pickerRe-export the DateRangePicker component.2 module(s), 1 public symbol(s)
date_range_picker.pyDateRangePicker — start + end date input with shared calendar popover.
DateRangePicker Start + end date input with shared calendar popover.
theme.pyDefault DateRangePicker theme.
bretzel.components.inputs.file_uploadui.file_upload — dropzone or compact-button file picker.2 module(s), 1 public symbol(s)
file_upload.pyFileUpload — dropzone or compact-button file picker.
FileUpload Dropzone or compact-button file picker.
theme.pyDefault FileUpload theme.
bretzel.components.inputs.formform component.2 module(s), 2 public symbol(s)
form.pyForm — wraps children in a <form> tag with submit handling.
contains_file_input Is there an <input type="file"> anywhere under these nodes? Form HTML form wrapper. Children are added via with block.
theme.pyDefault Form theme — a thin flex column.
bretzel.components.inputs.form_fieldform_field component.2 module(s), 1 public symbol(s)
form_field.pyFormField — wraps an input with label / hint / error display.
FormField Field wrapper : label on top, child input in the middle, hint or error below.
theme.pyDefault FormField theme.
bretzel.components.inputs.inputinput component.2 module(s), 1 public symbol(s)
input.pyInput — text input with prefix/suffix/icon slots.
Input Render a text input with distinct input and change events.
theme.pyDefault Input theme.
bretzel.components.inputs.month_pickermonth_picker component.2 module(s), 3 public symbol(s)
month_picker.pyMonthPicker — a MONTH field with a year grid in a popover.
month_to_ym Coerce a month value to "YYYY-MM". normalise_to_ym_js The free-input → YYYY-MM normaliser for value_expr. MonthPicker Render a month field with a year-grid popover.
theme.pyDefault MonthPicker theme.
bretzel.components.inputs.number_inputnumber_input component.2 module(s), 1 public symbol(s)
number_input.pyNumberInput — numeric input with vertical ± stepper buttons.
NumberInput Numeric input with vertical ± stepper buttons.
theme.pyDefault NumberInput theme.
bretzel.components.inputs.radioradio component.2 module(s), 2 public symbol(s)
radio.pyRadio + RadioGroup — single-choice input cluster.
RadioGroup Container for a cluster of Radio items. Owns the name and the bound value. Radio One choice inside a RadioGroup. Inherits name, value (binding), color, size from the group's reactive props at render time — explicit kwargs on the radio override per-item if needed.
theme.pyDefault themes for RadioGroup and Radio.
bretzel.components.inputs.selectselect component.2 module(s), 1 public symbol(s)
select.pySelect — custom popover-based combobox.
Select Styled combobox built on a button trigger + dropdown panel.
theme.pyDefault Select theme.
bretzel.components.inputs.signature_padui.signature_pad — sign with a finger or a mouse.2 module(s), 1 public symbol(s)
signature_pad.pySignaturePad — sign with a finger or a mouse, inside a form.
SignaturePad Surface de signature — pointeur / doigt → PNG en data-URL.
theme.pyDefault SignaturePad theme.
bretzel.components.inputs.sliderslider component.2 module(s), 1 public symbol(s)
slider.pySlider — drag-to-pick numeric value, single or range.
Slider Drag-to-pick numeric input, single or range.
theme.pyDefault Slider theme.
bretzel.components.inputs.switchswitch component.2 module(s), 1 public symbol(s)
switch.pySwitch — visual variant of checkbox with a sliding thumb.
Switch Boolean toggle rendered as a sliding rail.
theme.pyDefault Switch theme.
bretzel.components.inputs.textareatextarea component.2 module(s), 1 public symbol(s)
textarea.pyTextarea — multi-line text input.
Textarea Multi-line text input.
theme.pyDefault Textarea theme.
bretzel.components.inputs.time_pickertime_picker component.2 module(s), 3 public symbol(s)
theme.pyDefault TimePicker theme.
time_picker.pyTimePicker — time field with a two-column panel.
time_to_hhmm Coerce a time value to "HH:MM". normalise_to_hhmm_js The free-input → HH:MM normaliser for value_expr. TimePicker Render a time field with hour and minute panels.
bretzel.components.inputs.toggle_grouptoggle_group component.2 module(s), 2 public symbol(s)
theme.pyDefault themes for ToggleGroup and ToggleButton.
toggle_group.pyToggleGroup + ToggleButton — multi-button selector cluster.
ToggleGroup Cluster of ToggleButton items — single or multi-select. ToggleButton One item inside a ToggleGroup.
bretzel.components.inputs.week_pickerweek_picker component.2 module(s), 2 public symbol(s)
theme.pyDefault WeekPicker theme.
week_picker.pyWeekPicker — a WEEK field, selected by row.
normalise_to_week_js The free-input → start-of-week ISO normaliser. WeekPicker Render a week field with row-based day selection.
bretzel.components.layoutLayout (flex, grid, stack, container, card).
bretzel.components.layout.cardcard component.2 module(s), 1 public symbol(s)
card.pyCard — surface wrapper with V1's signature hover lift effect.
Card Surface wrapper. Pass href= to make the whole card a link (auto-enables hoverable), padding= for the inner spacing scale, hoverable=True to opt in to the lift effect manually.
theme.pyDefault Card theme.
bretzel.components.layout.carouselcarousel component.2 module(s), 1 public symbol(s)
carousel.pyCarousel — snapping scroll through a series of contents.
Carousel Render a snapping track whose direct children are slides.
theme.pyDefault Carousel theme.
bretzel.components.layout.containercontainer component.2 module(s), 1 public symbol(s)
container.pyContainer — centered max-width layout primitive.
Container Centered max-width column. Pass width= to pick the clamp.
theme.pyDefault Container theme.
bretzel.components.layout.draggabledraggable component.2 module(s), 1 public symbol(s)
draggable.pyDraggable — one grabbable item inside a Dropzone.
Draggable A grabbable wrapper around one item of a dropzone.
theme.pyTheme slots for ui.draggable.
bretzel.components.layout.dropzonedropzone component.3 module(s), 2 public symbol(s)
dropzone.pyDropzone — a region that receives dragged items.
Dropzone Render a drop target whose on_move handler receives a typed Move.
move.pyMove — what a drop reports to its on_move handler.
Move One completed drag, as the server sees it.
theme.pyTheme slots for ui.dropzone.
bretzel.components.layout.flexRe-export the Flex component.2 module(s), 1 public symbol(s)
flex.pyFlex — generic CSS-flex container (Archetype 2).
Flex A flex container with the full Tailwind axis API exposed.
theme.pyDefault Flex theme.
bretzel.components.layout.gridgrid component.2 module(s), 1 public symbol(s)
grid.pyGrid — CSS-grid container, sibling of Flex.
Grid Two-dimensional layout container.
theme.pyDefault Grid theme.
bretzel.components.layout.panepane component.2 module(s), 1 public symbol(s)
pane.pyPane — the region that scrolls.
Pane Render a scrolling column that occupies the remaining space.
theme.pyDefault theme for Pane — the region that scrolls.
bretzel.components.layout.resizableui.resizable / ui.resizable_panel — split panes.2 module(s), 3 public symbol(s)
resizable.pyResizable — panels separated by handles you drag.
normalize_weights Raw sizes → count percentages summing to 100. ResizablePanel Render one panel inside a resizable group. Resizable Render a group of panels separated by resize handles.
theme.pyDefault Resizable / ResizablePanel theme.
bretzel.components.layout.stackRe-export VStack, HStack.Re-export VStack, HStack. Both are tiny shortcuts on top of Flex that bake a direction in and offer a smaller kwargs surface for the common "list of items" layouts. There is no bare Stack — pick VStack / HStack explicitly, or drop to Flex for a runtime-chosen direction.1 module(s), 2 public symbol(s)
stack.pyVStack and HStack — Flex shortcuts with a baked direction.
VStack Vertical stack — Flex with direction="col" baked in. HStack Horizontal stack — Flex with direction="row" baked in.
bretzel.components.layout.viewportviewport component.2 module(s), 1 public symbol(s)
theme.pyDefault theme for Viewport — the full-screen frame.
viewport.pyViewport — the frame that takes the screen and never scrolls.
Viewport Render a full-screen frame whose regions scroll independently.
bretzel.components.metaThe framework's marker components: outlet, fragment, interval, title, meta_tag, and the each family. (page and layout are NOT here: they are decorators, in render/decorators/.)The framework's marker components: outlet, fragment, interval, title, meta_tag, and the each family. (page and layout are NOT here: they are decorators, in render/decorators/.)
bretzel.components.meta.fragmentfragment component.1 module(s), 1 public symbol(s)
fragment.pyFragment — children grouping with no DOM wrapper.
Fragment Wrap-less container — children render flat into the parent.
bretzel.components.meta.intervalinterval component.1 module(s), 1 public symbol(s)
interval.pyInterval — recurring client timer that fires a server action.
Interval Hidden recurring timer. Pairs with a ClientBinding gate so the cadence is stoppable without any server-side task lifecycle.
bretzel.components.meta.iterationReactive list-iteration family — keyed iteration + filter + paginate.Reactive list-iteration family — keyed iteration + filter + paginate. One discoverable home for the *_each generators, even though they straddle two layers by necessity : - each is defined HERE (each.py). The bretzel.render.iteration module only carries the key stack (_KEY_STACK / current_iteration_key / _extract_key), and neither defines nor re-exports each. - filter_each / paginate_each build *on* each by wrapping each item's body in a component (a bz-show window), so they are component-layer and live here. Re-exported together so callers — and the ui.* namespace — find the whole family in one place. Future reactive members (e.g. server-side sort / group are intentionally NOT here : reorder is a refreshable concern, cf. todo.md) would join this package.7 module(s), 7 public symbol(s)
_ref.pyThe JS subterm shared by the windowing generators.
window_ref value as a parenthesised JS subexpression.
drag_each.pyui.drag_each — iterate items, wrapping each in a ui.draggable.
drag_each Yield each item inside a ui.draggable. See module docstring.
each.pyui.each — keyed iteration generator (the base of the *_each family).
each Iterate over items while preserving stable per-item identity.
filter_each.pyui.filter_each — client-side filtered iteration.
filter_each Iterate items, wrapping each body in a client-side bz-show matching query against text(item). See module docstring.
limit_each.pyui.limit_each — client-side "first N" iteration.
limit_each Iterate items, showing only the first limit client-side.
paginate_each.pyui.paginate_each — client-side paginated iteration.
paginate_each Iterate items, showing only the current page's window client-side.
show_more.pyui.show_more — ui.limit_each + a "Show more" button.
show_more Iterate items first-count (client-side), then drop a "Show more" button after the rows. See the module docstring.
bretzel.components.meta.meta_tagmeta_tag component.1 module(s), 1 public symbol(s)
meta_tag.pyMetaTag — <meta> injection into the document <head>.
MetaTag <meta> element pushed into the request's head_extras.
bretzel.components.meta.outletoutlet component.1 module(s), 1 public symbol(s)
outlet.pyOutlet — page-content injection point inside an @layout.
Outlet <main> slot where the page content lands inside a layout.
bretzel.components.meta.titletitle component.1 module(s), 1 public symbol(s)
title.pyTitle — page-level <title> override.
Title Page-level <title> override (side-effect component).
bretzel.components.navigationNavigation between pages/sections.1 module(s), 10 public symbol(s)
_wiring.pyThe shared body of a navigation item — NavbarItem, SidebarItem, BottomBarItem.
capture_layout The enclosing layout's name, read at construction. current_path_scope The bz-data literal that declares the current_path signal. NavItemWiring What wire_nav_item resolved — the behaviour, not the render. wire_nav_item The prologue of a nav item's render() — reading + wiring. is_external_href An href that leaves the site — never partial-nav'd. apply_active_state Set the active state on attrs — three sources, in order. apply_partial_nav Wire the HTMX outlet swap when the item carries an href AND a layout was captured. apply_disabled Neutralise the item — a11y, tab order, click channels. render_badge A nav item's badge chip. current_path_resync_init bz-init that keeps current_path stuck to the real URL.
bretzel.components.navigation.bottom_barbottom_bar component.2 module(s), 2 public symbol(s)
bottom_bar.pyBottomBar / BottomBarItem — bottom-of-screen tab bar (mobile).
BottomBar Render a bottom navigation bar that tracks the current path. BottomBarItem Render a bottom-bar item with an icon, label, and optional badge.
theme.pyDefault theme for the BottomBar family (BottomBar / BottomBarItem).
bretzel.components.navigation.breadcrumbbreadcrumb component.2 module(s), 2 public symbol(s)
breadcrumb.pyBreadcrumb — page-location trail.
Breadcrumb Page-location trail with chevron-separated parents. BreadcrumbItem Render one breadcrumb segment with an optional icon and link.
theme.pyDefault Breadcrumb theme.
bretzel.components.navigation.navbarnavbar component.2 module(s), 3 public symbol(s)
navbar.pyNavbar / NavbarSection / NavbarItem — top navigation bar.
Navbar <header> top bar. Owns current_path for active links. NavbarSection One of three positional groupings inside a Navbar. NavbarItem Horizontal nav row — icon + label + optional badge.
theme.pyDefault theme for the Navbar family (Navbar / NavbarSection / NavbarItem).
bretzel.components.navigation.paginationpagination component.2 module(s), 2 public symbol(s)
pagination.pyPagination — page-navigation widget.
compute_range Return the page list to display, with "ellipsis" markers. Pagination Page navigation : *Prev* — N page buttons — *Next*.
theme.pyDefault Pagination theme.
bretzel.components.navigation.sidebarsidebar component.2 module(s), 7 public symbol(s)
sidebar.pySidebar / SidebarSection / SidebarItem — navigation rail.
Sidebar Render a collapsible application sidebar. SidebarTrigger Render a button that opens or closes a sidebar. SidebarSection Group of items with an optional uppercase label. SidebarTitle Render the sidebar title and optional home link. SidebarItem One nav row : icon + label + optional badge. SidebarFooter Render the footer region of a sidebar. SidebarFooterItem A clickable row inside a SidebarFooter popover.
theme.pyDefault theme for the Sidebar family (Sidebar / SidebarSection / SidebarItem).
bretzel.components.navigation.stepperstepper component.2 module(s), 3 public symbol(s)
stepper.pyStepper / Step / StepPanel — progress through ordered steps.
Stepper Render an ordered sequence of steps with matching content panels. Step Describe one step in a stepper. StepPanel Render content when its step is active.
theme.pyDefault Stepper / Step / StepPanel theme.
bretzel.components.navigation.tabstabs component.2 module(s), 3 public symbol(s)
tabs.pyTabs / Tab / TabPanel — switchable content panels.
Tabs Container that holds Tab buttons + TabPanel content. Tab One button inside a Tabs strip. TabPanel Content shown when its tab matches the active id.
theme.pyDefault Tabs / Tab / TabPanel theme.
bretzel.components.overlaySurfaces above flow (dialog, drawer, popover, etc.).2 module(s), 2 public symbol(s)
_anchored.pyThe shared render of the ANCHORED overlays — Dropdown and Popover.
render_anchored_overlay Wrapped trigger + teleported panel + wired root.
_modal.pyThe shared render of the two modal overlays — Dialog and Drawer.
render_modal_overlay Backdrop + container + panel (header, body) + wired root.
bretzel.components.overlay.dialogdialog component.2 module(s), 1 public symbol(s)
dialog.pyDialog — modal overlay with backdrop, escape, scroll lock.
Dialog Centered modal with backdrop + escape + scroll lock.
theme.pyDefault Dialog theme.
bretzel.components.overlay.drawerdrawer component.2 module(s), 1 public symbol(s)
drawer.pyDrawer — side-anchored sliding panel.
Drawer Side-anchored sliding panel.
theme.pyDefault Drawer theme.
bretzel.components.overlay.dropdowndropdown component.2 module(s), 2 public symbol(s)
dropdown.pyDropdown + DropdownItem — anchored menu of clickable rows.
Dropdown Anchored menu of clickable rows. DropdownItem One clickable row inside a Dropdown.
theme.pyDefault Dropdown + DropdownItem theme.
bretzel.components.overlay.popoverpopover component.2 module(s), 1 public symbol(s)
popover.pyPopover — anchored floating panel.
Popover Anchored floating panel toggled by a trigger element.
theme.pyDefault Popover theme.
bretzel.components.overlay.tooltiptooltip component.2 module(s), 1 public symbol(s)
theme.pyDefault Tooltip theme.
tooltip.pyTooltip — text panel shown on hover / focus of a wrapped trigger.
Tooltip Hover-/focus-revealed text panel.
bretzel.components.primitivesNon-interactive elementary blocks.
bretzel.components.primitives.audioaudio component.2 module(s), 1 public symbol(s)
audio.pyAudio — the thinnest of the media family, and it owns it.
Audio Render a native audio player with visible controls by default.
theme.pyDefault Audio theme — the repository's thinnest, and rightly so.
bretzel.components.primitives.codeRe-export the Code component.2 module(s), 2 public symbol(s)
code.pyCode — block code display with optional Pygments highlighting.
highlight_code Pygments highlight with a (text, lang) LRU cache. Code Block code with Pygments syntax highlighting.
theme.pyDefault Code theme.
bretzel.components.primitives.dividerdivider component.2 module(s), 1 public symbol(s)
divider.pyDivider — horizontal or vertical separator with optional label.
Divider Horizontal or vertical separator. orientation="vertical" flips the axis ; pass label="…" for the boxed-section look.
theme.pyDefault Divider theme.
bretzel.components.primitives.headingheading component.2 module(s), 1 public symbol(s)
heading.pyHeading — semantic h1–h6 with size decoupled from level.
Heading Semantic heading. Pass text positionally, set level= (int 1–6) for the HTML tag, size= to override the auto-derived visual size.
theme.pyDefault Heading theme.
bretzel.components.primitives.htmlhtml component.2 module(s), 1 public symbol(s)
html.pyHtml — the way out: injecting verbatim markup.
Html Inject trusted HTML verbatim without escaping it.
theme.pyDefault Html theme — deliberately almost empty.
bretzel.components.primitives.iconicon component.2 module(s), 1 public symbol(s)
icon.pyIcon — Iconify wrapper, set-agnostic.
Icon Inline icon. name accepts "save" (resolved against the theme's default set) or "lucide:save" (explicit set).
theme.pyDefault Icon theme.
bretzel.components.primitives.iframeiframe component.2 module(s), 1 public symbol(s)
iframe.pyIframe — a third-party document, bounded by default.
Iframe Embed a titled document with a secure sandbox by default.
theme.pyDefault Iframe theme.
bretzel.components.primitives.imageimage component.2 module(s), 1 public symbol(s)
image.pyImage — show an image, with its room reserved.
Image Render an image and optionally reserve its layout with ratio=.
theme.pyDefault Image theme.
bretzel.components.primitives.markdownRe-export the Markdown component.2 module(s), 1 public symbol(s)
markdown.pyMarkdown — render markdown text to styled HTML.
Markdown Block markdown rendering with bretzel typography. Server-only.
theme.pyDefault Markdown theme.
bretzel.components.primitives.menu_itemmenu_item primitive — shared base for clickable menu rows.1 module(s), 1 public symbol(s)
menu_item.pyMenuItem — shared base for clickable menu rows.
MenuItem Base clickable menu row. Subclasses provide THEME/THEME_KEY.
bretzel.components.primitives.spinnerspinner component.2 module(s), 1 public symbol(s)
spinner.pySpinner — pure-CSS loading indicator.
Spinner Loading indicator. Pass size= for the scale, color= for the tint — a rotating ring is the one built-in look.
theme.pyDefault Spinner theme.
bretzel.components.primitives.textRe-export the Text component.2 module(s), 1 public symbol(s)
text.pyText — typographic primitive (Archetype 1, leaf).
Text Inline / block text with typographic modifiers.
theme.pyDefault Text theme.
bretzel.components.primitives.videovideo component.3 module(s), 3 public symbol(s)
theme.pyDefault Video theme.
track.pyTrack — a subtitle track described as data.
Track Describe a timed media track such as captions, descriptions, or chapters. track Build a timed media track for ui.audio or ui.video.
video.pyVideo — a dressed <video>, not a player.
Video Render a native video player with reserved layout space.
bretzel.coreINTERNAL layer — pure framework primitives with no user-facing API.8 module(s), 20 public symbol(s)
errors.pyLayer 0 — the canonical framework exceptions.
BretzelError Generic runtime error from Bretzel internals. AuthRequiredError Raised when a user-scoped state is resolved with no user.
escape.pyHTML / attribute / JS escaping primitives.
escape_html Escape a string for use in HTML body content. escape_attr Escape a value for a double-quoted HTML attribute. escape_js Escape a string for inclusion as a JS string literal. escape_inline_json Defuse </ in a JSON payload embedded inside an HTML tag. serialize_attrs Serialize HTML attributes into a leading-space string.
identity.pyStable cross-render IDs.
hash_segment Stable 8-char hex digest used to compress IDs (and other stable wire ids, e.g. a @refreshable zone's bz-id). IdGenerator Generate stable child identifiers within one render scope.
invoke.pyCall APPLICATION code without ever blocking the event loop.
call_without_blocking Call fn without blocking the event loop.
payload.pyEventPayload — a typed value object a component sends with an action.
EventPayload Base for the typed payloads a component's runtime sends to a handler.
serialize.pyNode tree → HTML string.
serialize Render a Node tree to an HTML string.
tracking.pyObserver-pattern reactivity engine.
Observer Anything that can be invalidated when one of its dependencies changes. CircularDependencyError Raised when an observer is detected at two levels of the eval stack. DependencyTracker Coordinates dependency registration and invalidation.
tree.pyImmutable virtual-DOM nodes.
Node Marker base class. Concrete subclasses are immutable dataclasses. Element A single HTML-ish element with optional attributes and children. TextNode Plain text content. Escaped at serialization time. HtmlNode Pre-rendered raw HTML escape hatch. FragmentNode Children grouping with no DOM wrapper.
bretzel.introspectLayer 7 — the framework describes itself, and cannot lie.Layer 7 — the framework describes itself, and cannot lie. This module reads the installed code at the moment it is queried. That is what distinguishes it from an API catalogue: there is nothing to maintain, so nothing to let drift. It is also why it ships INSIDE the framework and cannot live in a separate package — a version gap between the describer and the described would make it lie, which is precisely the illness it cures. Three high-level entry points: - index — one line per ui.* symbol, the whole surface. - describe — a symbol's complete card, as text, on demand. - resolve — the SAME resolution, returned as a dataclass. It is the one a consumer calls: the CLI draws its --json from it, and the order of the tiers (module → component → symbol) is written only there. ⚠️ The emitters' output is UTF-8, arrows and quotation marks included. A consumer writing it to a stream owns its encoding — on a Windows console (cp1252) a bare print raises. The CLI does it for them (bretzel.cli.main); a home-made script must do it too. And the per-section readers, for a consumer composing their own: describe_state, describe_client_algebra, describe_toplevel_surface, describe_method_surface, describe_callable. The contract for a third-party consumer (living documentation, generator, MCP server) is bretzel.introspect.model: the dataclasses are imported in process, the text output is not parsed. The absence of a specialised section in the textual output does not mean the symbol is absent from the general resolution.13 module(s), 58 public symbol(s)
_signature.pyReading a live Python signature — the shared primitive.
type_label A compact, readable label for a resolved type. default_label The label of an already-known default value (outside a signature). describe_callable Read a callable's live signature.
algebra.pyThe Python→JS client binding algebra — read AND executed.
describe_client_algebra Read a binding class's live Python→JS algebra.
capabilities.pyWhat Bretzel can DO — the list no tree can give.
Capability One thing Bretzel makes possible, and where one enters it. capability_names The titles, in list order. render_capabilities The list as text — what bretzel describe capabilities returns.
components.pyThe ui.* catalogue — read live, never copied.
helper_kind The nature of a ui.* symbol that is not a component. ui_symbol_names Every public ui.<name> symbol, in declaration order. ui_name_of_class Component class → its ui.* call name. prop_vocabulary THEME_KEY → variant / size → accepted values. theme_vocabulary THEME_KEY → group → keys — what Theme(components={…}) can name. theme_shapes THEME_KEY → group → key → "str" or "dict" — the SHAPE the SHIPPED theme gives each entry. describe_component Read a Component subclass: family, tag, parameters, and the FIVE introspectable contracts (BINDABLE_PROPS / EVENTS / NAMED_SLOTS / IMPERATIVE / THEME's vocabulary) plus AUTONAME_FROM and THEME_KEY. describe_ui_symbol Classify a ui.<name> symbol and read it live. describe_components The whole ui.* catalogue, sorted by name.
methods.pyA NAMESPACE's callable surface — the generic primitive.
describe_method_surface Everything callable on cls as a public API. describe_namespace_surface The callables of names read on owner, in that order. return_label (function)
model.pyThe introspection dataclasses — and nothing else.
ParamInfo A parameter acceptable at the call site. CallableInfo Any callable read from its live signature. ComponentInfo A ui.* entry that is a Component subclass. FieldInfo A field of a state class. StateInfo A state class — server (4 scopes) or client. MethodInfo A public method read on a class. AlgebraOp An operation of the client binding algebra, with the JS it really emits — captured by a probe, not copied. ModuleSection The public surface of ONE framework module, classified by need. SurfaceSymbol A name from bretzel.__all__, classified by the need it covers. SymbolDetail The card of a public symbol that is not a ui.*. HelperInfo A ui.* entry that is not a component.
modules.pyThe public surfaces of the framework's modules, classified by need.
module_names The modules that have a classification table. public_owners Public name → the package exporting it, over the whole app surface. uncovered_owners Those of public_owners that no section classifies. describe_module Read a module's __all__ and classify every name by need. describe_modules Every covered section, in reading order. describe_toplevel_surface bretzel.__all__ classified — the surface one meets first. kind_of (function) first_doc_line (function) value_summary A constant's value — its summary, not its type's. summarize A symbol's index line: its value when it is one, otherwise the first line of its docstring.
package_tree.pyThe folder TREE — the framework describes its own layout.
SymbolLine A module's public symbol, and its first line. ModuleInfo A .py module, its reason to exist, and what it exposes. PackageNode A package, its reason to exist, and what it contains. describe_package The tree starting from name, docstrings included. walk The node and all its descendants, depth first. package_names Every package under root, dotted paths, sorted. render_tree The tree as text. No caller in the framework: bretzel describe <package> renders render_package, which does not use it. render_package A package's card — its reason to exist, its tree, its modules.
packages.pyThe components published by INSTALLED packages — and why it is not the same entry point as the roots to scan.
ThemeKeyCollision A package publishes a THEME_KEY the framework already carries. third_party_components The Component classes published by the installed packages. third_party_theme_vocabulary THEME_KEY → group → keys, for third-party components.
routing.pyKwarg routing — derived from the base layer, never copied.
Bucket One split_kwargs bucket, with what falls into it. describe_kwarg_routing The buckets, read from the base layer's constants.
state.pyThe state classes, read live.
describe_state Read a live state subclass.
symbols.pyThe card of a public symbol that is not a ui.*.
symbol_owners Public name → the modules exporting it, in reading order. symbol_names Every describable name outside ui.*, sorted. describe_symbol The card of a public symbol of a framework module.
theme_sheet.pyA component's THEME card — what describe X --theme returns.
theme_sheet ui_name's theme card, as text.
bretzel.introspect.emitProjections of bretzel.introspect.model — and nothing more.Projections of bretzel.introspect.model — and nothing more. An emitter is dumb: it formats already-built dataclasses, it computes nothing. That is what guarantees that the text and the JSON cannot diverge — they read the same data.1 module(s), 7 public symbol(s)
text.pyThe text emitter — two granularities, and that is the design's point.
render_index One line per ui.* symbol — plus a contracts line when the component carries any. render_detail A symbol's complete card. render_symbol The card of a symbol outside ui.*. render_module A module section, grouped by need. render_modules Every module section, in reading order. render_kwarg_routing Kwarg routing, DERIVED from the base layer's constants. render_bindable_matrix Each component's bindable surface, DERIVED.
bretzel.lintLayer 7 — the framework judges the code written against it.Layer 7 — the framework judges the code written against it. The counterpart of bretzel.introspect: that one describes, this one reports. The distinction is not cosmetic — it decides what can be extracted. describe reflects the installed code, so it must travel at its exact version, otherwise it lies; lint carries *rules*, knowledge that depends on no version, and it is the half that can leave the public repository one day. The lint-stays-extractable contract in the .importlinter file makes that a mechanical guarantee rather than an intention: no framework module outside cli may import this package. Two tiers, by safety and not by convenience: - run — static. AST only, nothing of the app is executed. It is the default, and it is what makes it safe to run over a third party's code. - run_deep — imports the application to query its map (undeclared routables, contract drift). Far more powerful, but it runs the user's code: it cannot be the default, and it takes not paths but a module:attribute target — the questions it asks have no answer in an isolated file.3 module(s), 13 public symbol(s)
corpus.pyDiscovering an app's files, and their AST — with no floor.
Module A source file and its tree, parsed once. discover The .py files under paths (files or folders). parse Parse a file, or return None when it is unreadable. modules Everything readable under paths, parsed. bound Expose found as the current pass's corpus. current The pass's corpus, or an empty tuple outside run. derived The pass's key derivation, built once. catalogue ui.<name> → its introspected card, read once per pass — the rules consult it for every module or every ui.* call.
deep.pyThe deep tier — the one that IMPORTS the application.
load_app Import module:attribute and return the object. run_deep The map lints on the app designated by module:attribute. lint_app The core, separated from the import.
report.pyWhat a rule returns, and what the command does with it.
Finding One finding, located, with enough to act on. Report One pass's aggregate. exit_code is the only translation into a verdict, and it lives here — not in a rule.
bretzel.lint.rulesThe rules — each pure, each enumerable.The rules — each pure, each enumerable. A rule has the signature check(module) -> list[Finding]. It knows neither corpus, nor floor, nor exit code: it reports on ONE module and returns bretzel.lint.report.Finding. The registry is a list, not a plugin system. The charter rules out a plugin system before the core stabilises, and a non-enumerable rule set would stop check saying what it can verify — which is precisely the question one asks a tool of this kind.19 module(s), 23 public symbol(s)
_theme_calls.pyReading a literal Theme(components={…}) — once only.
called_name The name called, bare or as an attribute — None otherwise. dict_items The "literal": value entries of a literal dict. components_arg The components= of a call that looks like Theme(...). component_maps Every components={…} of this module's Theme(...).
handlers.pyRule: a handler cannot be a lambda.
check (function)
injection.pyRule: ui.html with anything but a literal.
check (function)
kwargs.pyRule: a kwarg passed to ui.* that the component does not accept.
check The kwargs no component called here reads.
lifespan.pyRule: a TestClient built without ever entering the lifespan.
check The test clients that will never enter the lifespan.
loop_state.pyRule: a ServerState built in an async def body.
check The server-state constructions made from the loop.
nested_link.pyRule: a link INSIDE a link — the parser undoes the card.
check The anchors opened inside another anchor's body.
nested_page.pyRule: a @page declared in a function body, harvested by nothing.
check The marked pages no sweep can reach.
partial_sizes.pyRule: a theme that resizes PART of the form controls.
check The themes that resize only part of the family.
provenance.pyRule: a cast that erases a state value's PROVENANCE.
stripping_expr (form, read's source) when value erases the provenance. check The casts set on a two-way prop.
shape.pyRule: a theme override that keeps the NAME and changes the SHAPE.
check The theme overrides whose shape contradicts the shipped theme.
shared_counter.pyRule: an AppState total incremented without being declared additive.
check The AppState totals incremented without an additive declaration.
sizes.pyRule: SIBLING form controls at different sizes.
check One finding per neighbourhood whose controls do not agree.
specificity.pyRule: a class in classes= that the SAME prop already sets.
check The classes= entries a prop of the same call already sets.
tailwind.pyRule: an assembled Tailwind class only exists in dev.
check (function)
theme.pyRule: a Theme(components={…}) name that nothing reads.
check The theme names nothing will read.
transport.pyRule: an app does not drive the transport by hand.
check (function)
variant.pyRule: a variant= / size= value no table carries.
check The values no table — shipped or declared — carries.
zone_deps.pyRule: a zone listening on behalf of a NESTED zone.
check The dependencies a zone carries on another's behalf.
bretzel.probeBrowser-based tools for probing a running Bretzel application.6 module(s), 19 public symbol(s)
_browser.pyThe browser — one Chromium per process, one context per window.
shared_browser The process's Chromium — started on the first request. contexts count fresh contexts, closed together on exit.
_probe.pyThe probe — serves the app, opens the windows, records the findings.
ProbeFailedError Raised when at least one browser probe check fails. ScopeNotReadableError Raised when a probe cannot inspect the requested state scope. Net Record the network cost of a browser interaction. say Print, whatever happens to the console's encoding. Verdict (class) Probe (class) probe Serve an application, open browser windows, and run checks on exit.
_server.pyServing the app for the probe's duration — in a thread, or a subprocess.
free_port (function) resolve "module:attr" → the object. An object stays itself. serve Return (base_url, app_object_or_None).
_settle.pyWait for the STATE, never for a duration.
settle_page Return SETTLED, NOTHING_MOVED, NAVIGATED or TIMEOUT.
_sweep.pyThe free sweep — what nobody rewrites, so nobody forgets.
sweep Measure every window, at two sizes and in both themes.
_window.pyA window — a browser context, its page, what it has seen.
Box Describe an element's geometry in CSS pixels. Seen A request seen leaving from a window. ElementNotFoundError Raised when a selector matches no element in a probe window. DropMissedError Raised when a drag operation does not land on its intended target. Window Control one browser window during a probe.
bretzel.renderINTERNAL layer — server-driven HTML rendering implementation.12 module(s), 47 public symbol(s)
context.pyPer-request RenderContext + contextvars.ContextVar binding.
RenderContext The per-request scope object. current_context Return the active context. Raises if called outside a render scope. maybe_current_context Variant that returns None outside a render scope (no raise). page_scope_of The page token, derived from the request PATH. use_context Bind ctx as the active context for the duration of the block.
fusion.pyNo-div-soup fusion : attach bz-id to the natural root.
FusionConflict Kept as a public name for backwards compatibility. fuse_or_wrap Apply the no-div-soup rule and return one HTML element.
iteration.pyIteration key context — the stable-key stack consumed by components.
current_iteration_key Return the joined iteration key (or None outside any each loop). key_segment Push an identity segment onto the stack, outside any loop.
lang.pyWhich language to serve THIS request — and the word table that goes with it.
negotiate_language Choose a language from Accept-Language or use default. LanguageTables Store the framework text table for each declared language. resolve_language Resolve the language for the current request. Language Read or select the language for the current request.
partials.pyPartial rendering — single @refreshable section + state delta.
RenderResult The output of a render call ready for Layer 6 to wrap. render_partial Render refreshable regions and the client-state delta. push_title Announce title to the runtime through HX-Trigger. drain_refresh_queue Render every queued refreshable in one OOB-batched response.
pipeline.pyFull-page render orchestration — turns a @page function into HTML bytes.
render_page Render a full HTML5 document for page_fn.
screen.pyScreen — current viewport shape, read server-side from a cookie.
Screen Per-request viewport shape read from the bz_screen cookie.
serialize.pyPublic helper : Component → serialized HTML string.
serialize_html Render *component* in isolation and return pretty HTML.
shell.pyHTML5 document shell — assembles the bytes that go on the wire.
nav_progress_html The navigation bar, injected once per page. default_shell Assemble the complete HTML5 document. inline_scripts The inline bodies, named. Cf. _inline_scripts. ShellSources Everything the shell loads or runs — the surface a CSP covers. shell_sources Return the sources the HTML shell will actually emit. favicon_href The URL of the document's icon, for Bretzel(favicon=…).
texts.pyThe words the framework wrote itself, and how to replace them.
TextsError Raised when a texts= key does not match a known framework phrase. resolve_texts Merge application text overrides into the built-in English values. text Return a framework phrase for key in the application's language. template Return the raw framework text template before interpolation. plural Return the …_one or …_other variant of key for n.
types.pyStructural types used by the render layer.
BretzelApp The slice of Bretzel the render pipeline depends on.
vendor.pyThe three third-party scripts, served from your own host, not a CDN.
VendoredAsset A third-party script: its file name, its source, its fingerprint. vendor_dir ./.bretzel/vendor/ — the project cache, next to the cwd. cached_name Return the cache filename containing the expected content fingerprint. vendored_local_path Return the local cache path for asset whether or not it exists. vendored_is_available Return whether a vendored asset exists locally. route_for (function) url_for The URL to put in the <script>: local if present, CDN otherwise. download Download asset into the cache, fingerprint verified. download_all Everything that can be brought in-house, in the project cache. browser_css_asset The browser Tailwind compiler — the FOURTH third party. downloadable_assets Return every third-party asset that can be downloaded locally. ensure_vendored Download missing third-party assets without making startup fatal. vendored_assets Return the third-party scripts loaded by every page, in order. icon_cache_dir ./.bretzel/vendor/icons/ — created on demand. icon_payload Return an Iconify API response body from cache or upstream.
bretzel.render.decoratorsRender-layer decorators (@page, @layout, …).Render-layer decorators (@page, @layout, …). Internal aggregator — the user-facing surface lives on the Bretzel instance, which dispatches app.page(...) / app.layout(...) to these implementations.5 module(s), 21 public symbol(s)
download.py@download — the routable that returns a FILE, not a page.
DownloadAlreadyMarkedError Two @download on the SAME function — the second would erase the first. DownloadMeta Captured at decoration time, read by the route registrar. download Mark a function as the producer for a file served at GET path.
error.py@error_page(status_code) — register a custom HTTP error page.
ErrorMeta (class) error_page Mark a function as the custom page for an HTTP status code.
layout.py@layout — mark a function as a layout that wraps pages.
LayoutMeta Captured at decoration time. layout (function) layout (function) layout Mark a function as a layout. Free decorator — needs no app.
page.py@page — register a function as a routed page handler.
PageAlreadyMarkedError Two @page on the SAME function — the second would erase the first. PageMeta Captured at decoration time, read by the route registrar. page Mark fn as the handler for GET path (or other methods).
refreshable.py@refreshable — mark a function as a partial swap target.
state_qualname Return the stable wire identifier for a state class. zone_attrs The attributes a zone sets IN ADDITION to its bz-id. drain_pending_async_zones Await the bodies of the async zones set down during this render. RefreshableHandle Callable wrapper carrying refresh metadata. zone_ids_watching Return refreshable region ids that watch state_cls. enqueue_deps Enqueue every zone whose deps include a changed State class for the end-of-action refresh drain. broadcast_deps Fan out state-dirty for every changed state that a broadcast=[State] zone depends on, so OTHER clients refetch it. refreshable Wrap fn as a refreshable page region. refresh Force a refresh of a zone — the single imperative trigger.
bretzel.runtimeINTERNAL layer — browser transport and client runtime integration.6 module(s), 22 public symbol(s)
_build.pyAssemble the _src/[0-9]*_*.js sources in the order of their names.
build (function) check CI helper: non-zero when either bundle is stale vs _src/.
_minify.pyStrip comments and indentation from a JS bundle. Nothing else.
strip_comments src without its comments — strings, templates and regexes intact. minify The bundle without comments, indentation or blank lines.
envelope.pyEnvelope / patch serialisation — the V3 wire format server ↔ runtime.
Envelope Top-level shape of the <bz-envelope> payload. Patch Top-level shape of one <bz-patch> payload. default_endpoints The runtime endpoints baked into a fresh envelope. build_envelope Build a deterministic, JSON-friendly runtime envelope. serialize_envelope Render the complete <bz-envelope>…</bz-envelope> tag. build_patch Bundle the client states to send into a patch payload. serialize_patch Render the <bz-patch>…</bz-patch> tag, or "" if empty. error_envelope Render a <bz-patch> carrying a reserved _error directive. parse_client_payload Split form-data into (client state per instance) + (handler args).
protocol.pyWire-format constants — the only place these strings are defined.
is_public_asset_path Return whether path names a public framework asset. outlet_id_for Return the <main> id for layout_name's outlet.
verbs.pyClient verbs — BROWSER actions, written in Python.
copy Copy value to the clipboard when the action runs. print_page Open the browser print dialog when the action runs. fullscreen Enter fullscreen mode when the action runs. share Open the native share sheet, or copy the URL when sharing is unavailable. vibrate Vibrate the device when the action runs.
version.pyRuntime protocol version + compatibility check.
parse_major Extract the major-version segment of a vN.M[.K] string. check_compat Return True if the client's reported version is compatible.
bretzel.serverHTTP, authentication, routing, and application lifecycle services.15 module(s), 67 public symbol(s)
_dev.pyBretzel-owned dev watcher.
PortAlreadyTakenError The port is already held — said BEFORE launching anything. ensure_port_is_free Raise PortAlreadyTakenError if (host, port) is taken. run_dev_server Block on watchfiles' parent loop: spawn _run_uvicorn as a child, restart it on every *.py change under watch_dirs. Returns on Ctrl+C.
app.pyBretzel — the user-facing app class.
Bretzel The Bretzel application instance.
auth.pyAuthentication helpers for Bretzel applications.
resolve_cookie_secure Should the Secure attribute be set on the cookies? request_scheme A request's scheme, tolerating duck-typed objects. parse_cookies_from_scope Parse the Cookie header on an ASGI scope into a name→value dict. AuthUser Minimal auth identity — the framework only knows the id. login Open a session for user_id — the proof already happened. logout Clear the auth cookie + rotate the session id. session_key A key that lets another program act in THIS browser session. user_id Return the authenticated user id, or None for an anonymous request. is_authenticated Convenience boolean wrapper around user_id. verify_auth_cookie Validate a Bretzel_auth cookie and return the user id. verify_session_key Validate a session_key and return the session id it opens. resolve_identity The identity chain, played on a raw request. app_of The Bretzel instance reachable from a raw request.
config.pyResolved app configuration — populated once at Bretzel init.
ConfigError Raised at BretzelConfig construction when a required setting is missing or malformed. BretzelConfig The resolved, validated configuration of a Bretzel app.
crypto.pyKey derivation + signing primitives for the security layer.
derive_key Return a 32-byte key derived from master for purpose. sign Compute the HMAC-SHA256 hex digest of payload under key. verify Constant-time check that signature matches sign(key, payload).
errors.pyServer-layer error types + abort + default error pages.
abort Raise an HTTP error from inside a request handler. default_error_page Build a self-contained HTML5 error page.
feature.pyThe Feature contract — a colocated slice's public boundary.
FeatureError Raised when a feature contract is malformed, or a set of features doesn't form a valid graph (unknown dependency, cycle, name clash). Feature One feature's contract. Declared once per feature package :: validate_features Check a set of features forms a valid graph. ProvideInfo One item a feature exposes, classified by what it is. FeatureNode One feature in the app graph — its contract, with provides classified, plus its folder path (the group hierarchy). AppGraph The whole app, read from its feature contracts : the nodes, the routes they mount, and the dependency edges. This is the living skeleton — one source (the Feature objects), read live, so it can't drift from the app it describes. describe_app Read a set of feature contracts into an AppGraph. undeclared_provides L1 — registered routables (pages / error handlers) covered by NO Feature: they run, but the map does not see them and the graph does not validate them — the skeleton would lie by omission. DriftReport L2 — ONE feature's gap between its contract and its real imports. dependency_drift L2 — confront the DECLARED uses/reads with the REAL imports (AST of each feature's modules, already loaded in sys.modules).
handlers.pyStateless action dispatch — module::qualname + HMAC signing.
HandlerResolutionError Raised when an action_id cannot be resolved or its signature fails verification. encode_action_id Return <module>::<qualname> for a module-level callable. action_path The path this handler POSTs to — what a guard must let through. resolve_handler Look action_id up in sys.modules and return the callable. encode_args If handler carries bound args, return their base64-JSON form. decode_args Decode the _args form field (POST body) back into (args, kwargs). action_hmac_payload The exact byte string signed and verified for one action. sign_action Compute the HMAC-SHA256 signature for (action_id, args_blob, ts). verify_action Constant-time comparison of the supplied signature against the one we'd produce for (action_id, args_blob, ts).
idempotency.pyOpt-in handler idempotency (HMAC v2 — the "C" half).
idempotent Mark a handler idempotent for ttl seconds. idempotent_ttl The handler's idempotency TTL (seconds), or None if not marked. idempotency_key Compact, injection-safe dedup key for one signed request + user. MemoryIdempotencyStore Single-process store — a dict + lock with lazy expiry. RedisIdempotencyStore Multi-worker store — an atomic SET key 1 NX EX ttl.
lifecycle.pyStartup / shutdown orchestration.
bretzel_startup Run framework-side startup. Call before user hooks. bretzel_shutdown Run framework-side teardown. Call after user hooks (LIFO). build_middleware_stack Wrap the FastAPI app in framework + user middlewares.
navigation.pySending the browser elsewhere — from a handler or from a middleware.
response_is_read_by_htmx True when htmx will handle the headers of the response to request. redirect_response A response sending request to url, whatever its nature. redirect Navigate the browser to url after the current request. push_url Change the displayed URL without navigating or reloading the page. reload Reload the page displayed by the browser after the current request.
oauth.pyOAuth and OpenID Connect authentication providers.
OAuthError An OAuth transaction that does not complete, framework-side. OAuthProfile Represent the normalized user profile returned by an OAuth provider. OIDC Configure an OpenID Connect provider from its issuer metadata. OAuth2 Configure an OAuth 2 provider from explicit endpoint URLs.
pwa.pyPWA — the declaration that makes an app installable.
PWAIcon Describe one icon in the web application manifest. PWA Declare the metadata that makes an application installable.
security.pySecurity headers — the boring ones always, the CSP on request.
script_hash Return the 'sha256-…' of an inline <script> body. build_policy Compose the value of the Content-Security-Policy header.
sse.pySSE broker — per-session message queues + state subscription tracking.
SSEBroker Backend-agnostic protocol the framework holds at runtime. MemoryBroker In-process SSEBroker implementation. RedisBroker Cross-worker SSEBroker — a local queue engine plus a Redis Pub/Sub fanout of the state-dirty signal.
bretzel.server.decoratorsServer-side decorators : middleware, startup, shutdown, background.4 module(s), 9 public symbol(s)
background.py@background — fire-and-forget after-response work.
BackgroundContextError Raised when .schedule() runs with no live request bound. bind_background_tasks Bind tasks as the current request's background queue. BackgroundHandle Returned by background. .schedule(kwargs) enqueues the wrapped function onto the current request's background queue ; calling the handle directly (await handle(kwargs)) just runs the function — the escape for contexts with no request. background Mark fn as an after-response background task.
identity.py@auth.source and @auth.door — the two halves of identity.
source Declare an identity source checked after the signed cookie. door Declare a login provider and how its profile is handled.
lifecycle.py@app.startup / @app.shutdown decorators.
startup Register a startup hook. Hooks fire after framework internals. shutdown Register a shutdown hook. Hooks fire LIFO before framework teardown.
middleware.py@app.middleware — register a user-defined middleware.
middleware Append target to the app's user-middleware list.
bretzel.server.middlewareFramework middlewares wrapping the underlying FastAPI.Framework middlewares wrapping the underlying FastAPI. Inbound order (outermost → innermost): 0. SecurityHeadersMiddleware <.security.SecurityHeadersMiddleware> — sets the security headers on the response on the way back. The outermost of the five so as to cover what the layers below produce on their own (a CSRF 403, an auth 401). 1. SessionMiddleware <.session.SessionMiddleware> — mints / reads the Bretzel_session cookie; stashes session_id and parsed cookies on request.state. 2. CSRFMiddleware <.csrf.CSRFMiddleware> — verifies the per-session X-Bretzel-CSRF header on non-safe HTTP methods. Skipped for /_bretzel/action/* (those carry their own HMAC). 3. AuthMiddleware <.auth.AuthMiddleware> — verifies the Bretzel_auth cookie and pins request.state.user. 4. RenderContextMiddleware <.render_context.RenderContextMiddleware> — composes the bretzel.render.context.RenderContext that the rest of the pipeline reads from; buffers + parses the form body once and splits the V3 namespaced client-state fields (Class.key.field) from regular handler args.6 module(s), 8 public symbol(s)
_state.pyInternal helpers for the pure-ASGI middleware stack.
ensure_state Get or initialise the State object pinned on scope. read_header Return scope['headers']'s value for name or None.
auth.pyIdentity middleware — resolves request.state.user on every request.
AuthMiddleware Resolve request.state.user from the identity chain.
csrf.pyCSRF middleware — session-bound token + Origin/Referer check.
csrf_token_for Compute the CSRF token for session_id under csrf_key. CSRFMiddleware Verify the per-session CSRF token on non-safe HTTP methods.
render_context.pyRender-context middleware — the central piece.
RenderContextMiddleware Construct a per-request RenderContext and apply its accumulated cookies / headers to the outgoing response.
security.pyMiddleware that sets the security headers on every response.
SecurityHeadersMiddleware Set BORING_HEADERS and, if asked for, the CSP.
session.pySession-cookie middleware — Bretzel_session.
SessionMiddleware Read or mint the Bretzel_session cookie on every request.
bretzel.server.routingRoutes for pages, actions, partials.11 module(s), 12 public symbol(s)
_csv.pyCSV writing, shared by both download paths.
to_csv RFC 4180 text: one header row, then one record per line. columns_of The columns DERIVED from a list of dicts — key and label equal.
actions.pyPOST /_bretzel/action/{action_id} — the event-dispatch endpoint.
register_action_route Wire the single POST /_bretzel/action/{action_id:path} route.
api_docs.pyGET /docs — Swagger UI over the app's own JSON API, opt-in.
register_api_docs Mount /docs and declare the bearer scheme, if api_docs.
datatable.pyGET /_bretzel/datatable.csv — the Datatable's export endpoint.
register_datatable_export_route Wire the single GET /_bretzel/datatable.csv route.
downloads.pyMounting the @download routes.
register_download_routes Mount one GET route per function carrying _bz_download.
errors.pyException handlers — turn raised errors into Bretzel-rendered pages.
register_error_handlers Wire the four exception handlers on the FastAPI app.
manifest.pyGET /manifest.webmanifest — the app's manifest, when it declares one.
register_manifest_route Mount the manifest route, if there is a manifest.
pages.pyPage routing — turn @page("/path") into FastAPI routes.
register_pages Add every registered @page function to fastapi.
realtime.pyGET /_bretzel/refetch/{state}/{zone} — the per-zone refetch route.
register_realtime_route Wire GET /_bretzel/refetch/{state_qualname}/{zone_qualname}.
sse.pyGET /_bretzel/sse — the EventSource endpoint for realtime.
register_sse_route Wire GET /_bretzel/sse on fastapi.
static.pyFramework-served static assets — runtime.js, theme.css.
register_static_routes Wire the framework asset routes into fastapi.
bretzel.stateTyped state for Bretzel applications.6 module(s), 18 public symbol(s)
base.pyAbstract State + the _StateMeta metaclass.
State Abstract parent of all typed-state classes.
live_connection.pyLiveConnection — the state of the SSE link, held by the runtime.
LiveConnection Expose the state of the framework's real-time connection.
locking.pyThe lock an app asks for, around a read-modify-write.
LockTimeoutError Raised when a state lock cannot be acquired before its deadline. StateLock The context manager returned by MyState.lock().
registry.pyPer-request state registry.
ScopeConfigError Raised when scope-specific identity is missing (no session id …). StateHydrationError Raised when server state cannot be hydrated safely. current_registry Return the registry bound to the active async task, if any. use_registry Bind a registry as the active one for the current task. StateRegistry Per-request resolver, hydrator and committer.
types.pyThe business types a state field can carry, and how they travel.
register_type Register how cls is encoded to and decoded from JSON. encode_value Render value in a form json accepts. decode_value Read raw back as a type_, or return it unchanged. is_storable Can the declared type REACH the store, AND come back from it?
url.pyThe state fields an app makes addressable — the URL as state.
AddressableFieldError Invalid URL declaration, or two states claiming the same name. addressable_fields {field name: parameter name} declared by cls. would_publish What addressable=True would publish — VALIDATED, therefore true. apply_url_params Seed the declared fields from params. Returns the names touched. collect_url_params {parameter: value} for every declared field of instances.
bretzel.state.datatableTyped state and reader queries for data tables.2 module(s), 2 public symbol(s)
query.pyQuery — what the reader asked for, handed to a rows callable.
Query One reader's view of a table : what to match, how to order, which slice.
state.pyDatatableState — the query a Datatable reads and writes.
DatatableState The query behind one Datatable — sort, page, search.
bretzel.state.fieldsField descriptors and decorators (internal aggregator).Field descriptors and decorators (internal aggregator). The user-facing surface lives in bretzel.state ; this package only groups the implementation files for cohesion.3 module(s), 11 public symbol(s)
computed.py@computed decorator and the ComputedProperty descriptor.
ComputedProperty Descriptor backing a @computed declaration. computed Mark a method as a derived, auto-tracked, cached property.
descriptor.pyField descriptor — the storage / access primitive for typed state.
coerce_form_value (provided, value) — a submitted string in the declared type. assign_fields Write several fields as ONE mutation. (errors, rejected). Field Per-attribute descriptor. field Declare a typed state field.
validator.pyValidator declarations for typed state.
FormError Report a validation error for an entire state instance. Validator Wrapper around a validator callable. validator (function) validator (function) validator Mark a function as a validator.
bretzel.state.persistenceStorage backends and the ClientState field-materialisation helpers.Storage backends and the ClientState field-materialisation helpers. Internal aggregator — the user-facing API lives in bretzel.state (MemoryBackend, RedisBackend, Backend). The V3 wire format itself lives in bretzel.runtime.envelope.4 module(s), 5 public symbol(s)
base.pyStorage backend protocol.
Backend Async key-value store with scope-aware key namespacing.
client_bridge.pyField materialisation helpers for ClientState wire payloads.
instance_key Return the wire key for state : "<ClassName>.<key>". full_field_dict Read every declared field, materialising defaults.
memory.pyIn-memory storage backend for dev / tests.
MemoryBackend Backend implementation backed by a process-local dict.
redis.pyRedis storage backend for production deployments.
RedisBackend Backend implementation backed by redis.asyncio.
bretzel.state.scopesState scopes — internal aggregator.State scopes — internal aggregator. The user-facing surface (ServerState, ClientState plus the sugar aliases) is re-exported by bretzel.state. This package groups the implementations only.2 module(s), 6 public symbol(s)
client.pyClientState — typed state living in the browser.
rendering_scope Mark the active task as 'rendering'. ReactivityError Raised when a ClientBinding is misused server-side. ClientBinding Wrapper carrying field metadata + the current server-side value. ClientExpression Build a browser-side expression from one or more client bindings. ClientState Typed state mirrored into the browser by the runtime.
server.pyServerState — typed state living on the server.
ServerState A typed state persisted on the server side.
bretzel.themeVisual identity, palettes, and Tailwind CSS generation.11 module(s), 30 public symbol(s)
bridges.pyThe colour bridges — twelve steps derived from one source hue.
bridge_class A colour's bridge class name. primary → bz-c-primary. bridged_color_names The colours that receive a bridge. readable_step_pct The hue percentage of step step, backed off if necessary. generate_color_bridges The bridges' CSS block — one rule per colour.
build.pyStandalone Tailwind v4 binary downloader + compile orchestration.
download_binary Download the Tailwind v4 standalone binary if absent. scan_roots The folders the compiler will read, for THIS input CSS. get_or_build_css Return a compiled style.css string for theme_css.
color_scheme.pyColorScheme — current color mode as a framework-owned ClientState.
ColorScheme Framework-owned color mode (singleton via the default key).
compiler.pySubprocess wrapper around the Tailwind v4 / Lightning CSS binary.
CompilerError Raised when the binary cannot be located or returns a non-zero exit code. The message includes whatever the binary printed to stderr so the user has something actionable on hand. find_lightning_binary Resolve the Tailwind v4 / Lightning CSS binary. CompileResult Return value of a successful one-shot compile. compile_with_lightning One-shot compile : feed theme_css to the binary, write to output_path. start_lightning_watch Spawn the binary in --watch mode and return the live process.
config.pyUser-facing theme configuration dataclasses.
IconConfig Defaults consumed by the ui.icon(...) component. ScrollbarConfig Style for the synthesised scrollbar (WebKit + Firefox).
css.pyFull theme.css generator.
generate_scrollbar_css Build the scrollbar rules for both WebKit and Firefox. strip_safelist Strip the scan instructions from the theme CSS — the @source inline(...) safelist and the @source "<dir>" roots. strip_scan_roots Strip the @source "<dir>" roots — and NOTHING else. generate_theme_css_full Assemble the full theme.css Lightning CSS will ingest.
palette.pyResolved palette — semantic + extras, with auto-foreground derivation.
ThemeError Raised on invalid theme input (missing slot, unknown color, …). resolve_color_pair Return (bg_hex, fg_hex) for a single hex. ResolvedColor A color name + hex pair + the CSS class names that point to it. Palette Resolved palette — semantic + extras for both light and dark modes.
slots.pyPure helpers for component-theme slot resolution and override merging.
merge_component_themes Deep-merge override on top of base — non-mutating. validate_component_overrides Raise when an override names something nothing will read.
sources.pyThe roots the production compiler SCANS — and who declares them.
discovered_source_roots The roots installed packages declare, sorted. all_source_roots The framework package, then what the others declare. generate_source_directives Return the Tailwind v4 @source "<dir>"; block for roots.
tailwind.pyGenerate the Tailwind v4 @theme block.
generate_theme_css Build the @import + @theme + .dark blocks. generate_safelist_comment Return a Tailwind v4 @source inline(...) directive.
tokens.pySemantic / palette name catalogue + type literals.

What this page does not show

Of a symbol, the tree gives the name and the first line. Not its parameters, not its slots, not its events: there are 2 827 lines of those for the 111 components alone, and showing them here would make a page nobody would read. The catalogue has its own page, and `bretzel describe <name>` returns the complete sheet on the command line.
ui.* catalogueCheat sheetBrowser capabilities