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