httk.serve.web.widgets

Static, safe widget authoring contracts and discovery helpers.

Submodules

• httk.serve.web.widgets.assets
• httk.serve.web.widgets.core
• httk.serve.web.widgets.extraction
• httk.serve.web.widgets.loader
• httk.serve.web.widgets.optimade_assets
• httk.serve.web.widgets.optimade_fields
• httk.serve.web.widgets.optimade_table
• httk.serve.web.widgets.table

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.

Exceptions

OptimadeTableProtocolError

A declared OPTIMADE table shell cannot meet the browser protocol.

Classes

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

Functions

function_widget(render, *[, name, source])	Wrap a callable as a FunctionWidget.
trusted_html(value)	Mark a widget's reviewed HTML output as trusted.
optimade_protocol_asset()	Return the registered-compatible built-in OPTIMADE protocol module.
optimade_protocol_href(context)	Return the protocol module URL for a page.

Package Contents

httk.serve.web.widgets.MAX_WIDGET_ASSET_BYTES = 1000000

Largest individual trusted widget asset accepted by WidgetAsset.

httk.serve.web.widgets.SUPPORTED_WIDGET_ASSET_CONTENT_TYPES

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

class httk.serve.web.widgets.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

class httk.serve.web.widgets.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.

class httk.serve.web.widgets.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.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.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]]

class httk.serve.web.widgets.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] = ()

httk.serve.web.widgets.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.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.SiteWidgetLoader(widgets_dir)

Load site widgets without allowing paths to escape their directory.

Parameters:

widgets_dir (pathlib.Path) – Directory containing trusted site widget modules.

widgets_dir

available()

List valid site-local widget modules.

Returns:

Sorted (name, source path) pairs.

Return type:

list[tuple[str, str]]

resolve(name)

Resolve and load one site-local widget.

Parameters:

name (str) – Site widget name beginning with site..

Returns:

Loaded widget, or None when the name or file is absent.

Raises:

ValueError – If the widget module or definition is invalid.

Return type:

httk.serve.web.widgets.core.Widget | None

httk.serve.web.widgets.optimade_protocol_asset()

Return the registered-compatible built-in OPTIMADE protocol module.

Returns:

The protocol module asset used by optimade_table.

Return type:

httk.serve.web.widgets.core.WidgetAsset

httk.serve.web.widgets.optimade_protocol_href(context)

Return the protocol module URL for a page.

Parameters:

context (httk.serve.web.widgets.core.WidgetContext) – Widget invocation context.

Returns:

Deployment-relative protocol module URL.

Return type:

str

exception httk.serve.web.widgets.OptimadeTableProtocolError

Bases: ValueError

A declared OPTIMADE table shell cannot meet the browser protocol.