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_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	An immutable adapter for the common module-level render facade.
Widget	Advanced immutable widget definition protocol.
WidgetAsset	An immutable, deployment-relative asset declared by trusted widget code.
WidgetContext	Immutable request and page information made available to widgets.
WidgetRegistry	Registry for built-ins; aliases never participate in site resolution.
WidgetRenderResult	An explicitly trusted HTML result returned by a widget.
SiteWidgetLoader	Load src/widgets/<name>.py without allowing paths to escape it.

Functions

function_widget(→ FunctionWidget)	Wrap a callable as a FunctionWidget.
trusted_html(→ WidgetRenderResult)	Mark a widget's reviewed HTML output as trusted.

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

An immutable adapter for the common module-level render facade.

name: str

render_function: WidgetRenderer

source: str

render(context: WidgetContext, **props: object) → str | WidgetRenderResult

class httk.serve.web.widgets.Widget

Bases: Protocol

Advanced immutable widget definition protocol.

property name: str

property source: str

render(context: WidgetContext, **props: object) → str | WidgetRenderResult

class httk.serve.web.widgets.WidgetAsset

An immutable, deployment-relative asset declared by 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.

path: str

content: bytes

content_type: str

class httk.serve.web.widgets.WidgetContext

Immutable request and page information made available to widgets.

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

Registry for built-ins; aliases never participate in site resolution.

register(widget: Widget, *, alias: str | None = None) → None

resolve(name: str) → Widget | None

available() → list[tuple[str, str]]

class httk.serve.web.widgets.WidgetRenderResult

An explicitly trusted HTML result returned by a widget.

html: str

assets: tuple[WidgetAsset, Ellipsis] = ()

httk.serve.web.widgets.function_widget(render: WidgetRenderer, *, name: str = '', source: str = '') → FunctionWidget

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.

httk.serve.web.widgets.trusted_html(value: str) → WidgetRenderResult

Mark a widget’s reviewed HTML output as trusted.

class httk.serve.web.widgets.SiteWidgetLoader(widgets_dir: pathlib.Path)

Load src/widgets/<name>.py without allowing paths to escape it.

widgets_dir

available() → list[tuple[str, str]]

resolve(name: str) → httk.serve.web.widgets.core.Widget | None

exception httk.serve.web.widgets.OptimadeTableProtocolError

Bases: ValueError

A declared OPTIMADE table shell cannot meet the browser protocol.