httk.serve.web.widgets.core

The public contracts for static httk-serve widgets.

Attributes

MAX_WIDGET_ASSET_BYTES	Largest individual trusted widget asset accepted by WidgetAsset.
SUPPORTED_WIDGET_ASSET_CONTENT_TYPES	The deliberately small content-type vocabulary for internal widget assets.
WidgetRenderer
BUILTIN_WIDGETS

Classes

WidgetAsset	Declare an immutable, deployment-relative asset from trusted widget code.
WidgetContext	Provide immutable request and page information to a widget.
WidgetRenderResult	Return explicitly trusted HTML and its declared widget assets.
Widget	Define the advanced immutable widget protocol.
FunctionWidget	Adapt a module-level render facade to the widget protocol.
WidgetRegistry	Register built-in widgets whose aliases do not resolve site widgets.

Functions

function_widget(render, *[, name, source])	Wrap a callable as a FunctionWidget.
trusted_html(value)	Mark a widget's reviewed HTML output as trusted.

Module Contents

httk.serve.web.widgets.core.MAX_WIDGET_ASSET_BYTES = 1000000

Largest individual trusted widget asset accepted by WidgetAsset.

httk.serve.web.widgets.core.SUPPORTED_WIDGET_ASSET_CONTENT_TYPES

The deliberately small content-type vocabulary for internal widget assets.

class httk.serve.web.widgets.core.WidgetAsset

Declare an immutable, deployment-relative asset from trusted widget code.

path is relative to /_httk/serve/assets/ and is never interpreted as a filesystem path. The engine serves only assets it has registered while rendering this site instance.

Parameters:

• path – Safe path below /_httk/serve/assets/.

• content – Immutable asset bytes.

• content_type – Supported asset content type.

path: str

content: bytes

content_type: str

class httk.serve.web.widgets.core.WidgetContext

Provide immutable request and page information to a widget.

Parameters:

• route – Route containing the widget.

• render_mode – serve for live rendering or publish for static output.

• widget_id – Stable identifier for this widget placement.

• query – Request query values.

• postvars – Parsed request body values.

• page – Page metadata and context.

• source_path – Source file containing the widget invocation.

• url_for – Builder for site-relative URLs.

• absolute_url_for – Builder for absolute site URLs.

• table_runtime – Engine-local table runtime when available.

route: str

render_mode: str

widget_id: str

query: collections.abc.Mapping[str, str]

postvars: collections.abc.Mapping[str, str]

page: collections.abc.Mapping[str, object]

source_path: pathlib.Path

url_for: collections.abc.Callable[[str], str]

absolute_url_for: collections.abc.Callable[[str], str]

table_runtime: object | None = None

class httk.serve.web.widgets.core.WidgetRenderResult

Return explicitly trusted HTML and its declared widget assets.

Parameters:

• html – Trusted HTML output.

• assets – Immutable assets used by the output.

html: str

assets: tuple[WidgetAsset, Ellipsis] = ()

class httk.serve.web.widgets.core.Widget

Bases: Protocol

Define the advanced immutable widget protocol.

property name: str

Return the widget’s canonical name.

property source: str

Return the widget’s source identifier.

render(context, **props)

Render trusted widget output for one invocation.

httk.serve.web.widgets.core.WidgetRenderer

class httk.serve.web.widgets.core.FunctionWidget

Adapt a module-level render facade to the widget protocol.

Parameters:

• name – Canonical widget name.

• render_function – Function used to render the widget.

• source – Source identifier for diagnostics and discovery.

name: str

render_function: WidgetRenderer

source: str

render(context, **props)

Render the widget through its wrapped callable.

Parameters:

• context (WidgetContext) – Immutable widget invocation context.

• **props (object) – Literal widget properties.

Returns:

HTML string or explicitly trusted render result.

Return type:

str | WidgetRenderResult

httk.serve.web.widgets.core.function_widget(render, *, name='', source='')

Wrap a callable as a FunctionWidget.

Site-local modules normally need no wrapper: a module-level render is discovered automatically. The helper is useful for explicit definitions.

Parameters:

• render (WidgetRenderer) – Function used to render the widget.

• name (str) – Canonical widget name.

• source (str) – Source identifier for diagnostics and discovery.

Returns:

Immutable function-backed widget.

Return type:

FunctionWidget

httk.serve.web.widgets.core.trusted_html(value)

Mark a widget’s reviewed HTML output as trusted.

Parameters:

value (str) – HTML reviewed by the widget author.

Returns:

Trusted widget render result.

Return type:

WidgetRenderResult

class httk.serve.web.widgets.core.WidgetRegistry

Register built-in widgets whose aliases do not resolve site widgets.

register(widget, *, alias=None)

Register one built-in widget and optional display alias.

Parameters:

• widget (Widget) – Built-in widget to register.

• alias (str | None) – Optional shorthand alias.

Raises:

ValueError – If the name or alias is already registered.

resolve(name)

Resolve a built-in name or alias.

Parameters:

name (str) – Built-in widget name or alias.

Returns:

Matching widget, or None when absent.

Return type:

Widget | None

available()

List built-in widget names and source identifiers.

Returns:

Sorted (name, source) pairs.

Return type:

list[tuple[str, str]]

httk.serve.web.widgets.core.BUILTIN_WIDGETS