httk.serve.web.widgets.table

The built-in, cursor-paginated httk.serve.table widget.

Attributes

TABLE_ENDPOINT
TABLE_ASSET_ROOT
DEFAULT_PAGE_SIZE
MAX_PAGE_SIZE
MAX_CURSOR_CHARS
MAX_TOKEN_BYTES
MAX_TOKEN_PAYLOAD_BYTES
MAX_TABLE_HTML_BYTES
MAX_TABLE_RESPONSE_BYTES
TOKEN_VERSION
DEFAULT_TOKEN_TTL_SECONDS

Exceptions

TableProtocolError	An expected bad table declaration, continuation, or provider result.
TableContinuationError	A continuation token did not meet the endpoint protocol.
TableContinuationExpired	A valid continuation token has passed its expiry.
TableProviderError	A site-local provider could not safely supply the requested page.
TableRevisionMismatch	A provider changed a revision-pinned result while paging.

Classes

TableTokenSigner	Authenticate, but do not encrypt, bounded table continuation state.
TableRuntime	Dispatch providers, render table pages, and authenticate continuations.
TableWidget	Adapt the built-in table runtime to the widget protocol.

Module Contents

httk.serve.web.widgets.table.TABLE_ENDPOINT = '/_httk/serve/table/page'

httk.serve.web.widgets.table.TABLE_ASSET_ROOT = '/_httk/serve/assets'

httk.serve.web.widgets.table.DEFAULT_PAGE_SIZE = 50

httk.serve.web.widgets.table.MAX_PAGE_SIZE = 500

httk.serve.web.widgets.table.MAX_CURSOR_CHARS = 16384

httk.serve.web.widgets.table.MAX_TOKEN_BYTES = 48000

httk.serve.web.widgets.table.MAX_TOKEN_PAYLOAD_BYTES = 32768

httk.serve.web.widgets.table.MAX_TABLE_HTML_BYTES = 512000

httk.serve.web.widgets.table.MAX_TABLE_RESPONSE_BYTES = 600000

httk.serve.web.widgets.table.TOKEN_VERSION = 1

httk.serve.web.widgets.table.DEFAULT_TOKEN_TTL_SECONDS = 900

exception httk.serve.web.widgets.table.TableProtocolError

Bases: ValueError

An expected bad table declaration, continuation, or provider result.

exception httk.serve.web.widgets.table.TableContinuationError

Bases: TableProtocolError

A continuation token did not meet the endpoint protocol.

exception httk.serve.web.widgets.table.TableContinuationExpired

Bases: TableContinuationError

A valid continuation token has passed its expiry.

exception httk.serve.web.widgets.table.TableProviderError

Bases: TableProtocolError

A site-local provider could not safely supply the requested page.

exception httk.serve.web.widgets.table.TableRevisionMismatch

Bases: TableProviderError

A provider changed a revision-pinned result while paging.

class httk.serve.web.widgets.table.TableTokenSigner(secret=None)

Authenticate, but do not encrypt, bounded table continuation state.

Continuation state expires and cursor values must not contain secrets.

Parameters:

secret (str | bytes | None) – Optional signing secret; generated per process when omitted.

sign(payload)

Sign canonical continuation state.

Parameters:

payload (collections.abc.Mapping[str, object]) – Bounded JSON-like continuation state.

Returns:

Authenticated continuation token.

Raises:

TableProtocolError – If the state or token exceeds protocol limits.

Return type:

str

verify(token)

Verify and decode an authenticated continuation token.

Parameters:

token (object) – Token supplied by the browser.

Returns:

Authenticated continuation state.

Raises:

TableContinuationError – If the token is malformed or unauthenticated.

Return type:

dict[str, object]

class httk.serve.web.widgets.table.TableRuntime(*, engine, token_secret=None, token_ttl_seconds=DEFAULT_TOKEN_TTL_SECONDS)

Dispatch providers, render table pages, and authenticate continuations.

Parameters:

• engine (httk.serve.web.engine.site_engine.SiteEngine) – Site engine that owns this runtime.

• token_secret (str | bytes | None) – Optional signing secret for continuation tokens.

• token_ttl_seconds (int) – Lifetime of authenticated continuation tokens.

engine

signer

token_ttl_seconds = 900

render(context, **props)

Render the first bounded table page and live pagination controls.

Static publication renders only the first page with pagination disabled; live rendering registers the browser assets and continuation endpoint.

Parameters:

• context (httk.serve.web.widgets.core.WidgetContext) – Immutable widget invocation context.

• **props (object) – Literal table provider and presentation properties.

Returns:

Rendered table shell and any live assets.

Raises:

• TableProtocolError – If widget properties or provider state are invalid.

• TableProviderError – If the site provider cannot supply the page.

Return type:

httk.serve.web.widgets.core.WidgetRenderResult

continuation(payload)

Resolve one authenticated browser continuation request.

Parameters:

payload (object) – Request mapping containing token, route, and widget ID.

Returns:

Rendered next-page body and continuation metadata.

Raises:

• TableContinuationError – If the request or token is invalid.

• TableContinuationExpired – If the token has expired.

• TableRevisionMismatch – If the provider revision changed.

• TableProviderError – If the provider cannot supply the page.

Return type:

dict[str, object]

class httk.serve.web.widgets.table.TableWidget

Adapt the built-in table runtime to the widget protocol.

name = 'httk.serve.table'

source = 'httk.serve.web.widgets.table'

render(context, **props)

Render a table through the engine-local table runtime.

Parameters:

• context (httk.serve.web.widgets.core.WidgetContext) – Immutable widget invocation context.

• **props (object) – Literal table provider and presentation properties.

Returns:

Rendered table shell and any live assets.

Raises:

TableProtocolError – If the context has no table runtime.

Return type:

httk.serve.web.widgets.core.WidgetRenderResult