httk.serve.web.providers

Small, dependency-free contracts for site-local paginated data providers.

Attributes

MAX_CURSOR_CHARS

MAX_ROW_DATA_BYTES

Classes

ProviderContext

Provide immutable site-local context to a table provider.

TableRequest

Describe one bounded page request passed to a table provider.

TableColumn

Describe one table column and its presentation-only metadata.

TablePage

Represent one bounded page of presentation rows and opaque cursors.

Functions

immutable_mapping(values)

Snapshot mappings and standard containers into immutable values.

Module Contents

httk.serve.web.providers.MAX_CURSOR_CHARS = 16384[source]
httk.serve.web.providers.MAX_ROW_DATA_BYTES = 512000[source]
httk.serve.web.providers.immutable_mapping(values)[source]

Snapshot mappings and standard containers into immutable values.

Other leaves are preserved as-is.

Parameters:

values (collections.abc.Mapping[str, object]) – String-keyed mapping to snapshot.

Returns:

Mapping proxy containing immutable mappings and standard containers.

Return type:

collections.abc.Mapping[str, object]

class httk.serve.web.providers.ProviderContext[source]

Provide immutable site-local context to a table provider.

Parameters:

  • route – Route containing the table widget.

  • widget_id – Stable identifier of the table widget on the route.

  • query – Request query values.

  • page – Page context supplied by the site.

  • global_data – Site-global data supplied by startup code.

route: str[source]
widget_id: str[source]
query: collections.abc.Mapping[str, str][source]
page: collections.abc.Mapping[str, object][source]
global_data: collections.abc.Mapping[str, object][source]
url_for(route, *, query=None)[source]

Build a site-local route URL without exposing the ASGI request.

Parameters:
Returns:

Site-local URL for the route.

Raises:

  • ValueError – If the route is not a safe relative site route.

  • TypeError – If query keys or values are not strings.

Return type:

str

class httk.serve.web.providers.TableRequest[source]

Describe one bounded page request passed to a table provider.

Parameters:

  • page_size – Maximum number of rows requested.

  • cursor – Opaque provider cursor for continuation.

  • revision – Optional provider revision pinned across pages.

page_size: int = 50[source]
cursor: str | None = None[source]
revision: str | None = None[source]
class httk.serve.web.providers.TableColumn[source]

Describe one table column and its presentation-only metadata.

Parameters:

  • key – Stable row value key.

  • label – Accessible column label.

  • align – Optional horizontal alignment.

  • class_name – Optional whitespace-free CSS class name.

key: str[source]
label: str[source]
align: str | None = None[source]
class_name: str | None = None[source]
classmethod from_value(value)[source]

Adapt a compact column declaration to a table column.

Parameters:

value (Self | str | collections.abc.Mapping[str, object]) – Existing column, string key, or explicit field mapping.

Returns:

Normalized table column.

Raises:

  • TypeError – If the declaration has an unsupported shape.

  • ValueError – If the declaration contains unknown or invalid fields.

Return type:

Self

class httk.serve.web.providers.TablePage[source]

Represent one bounded page of presentation rows and opaque cursors.

Parameters:

  • rows – Presentation-only row mappings.

  • columns – Table columns.

  • next_cursor – Opaque cursor for the next page.

  • previous_cursor – Opaque cursor for the previous page.

  • total – Optional exact total row count.

  • revision – Optional provider revision for stable pagination.

rows: tuple[collections.abc.Mapping[str, object], Ellipsis][source]
columns: tuple[TableColumn, Ellipsis][source]
next_cursor: str | None = None[source]
previous_cursor: str | None = None[source]
total: int | None = None[source]
revision: str | None = None[source]
classmethod from_rows(rows, *, columns, next_cursor=None, previous_cursor=None, total=None, revision=None)[source]

Construct a page while adapting compact column declarations.

Parameters:
Returns:

Normalized table page.

Return type:

Self

classmethod from_result(value)[source]

Normalize a table page or equivalent explicit mapping.

Parameters:

value (object) – Provider result to normalize.

Returns:

Normalized table page.

Raises:

  • TypeError – If the result is not a table page or mapping.

  • ValueError – If the mapping contains invalid fields or values.

Return type:

Self