httk.serve.web¶

Provide the public API for serving and publishing httk web sites.

Submodules¶

Attributes¶

SITE_RESOURCES_KEY

Stable global_data key through which site startup code gets resources.

Classes¶

`ProviderContext`	Provide immutable site-local context 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.
`TableRequest`	Describe one bounded page request passed to a table provider.
`SiteResources`	Callbacks owned by one `httk.serve.web.engine.site_engine.SiteEngine`.

Functions¶

`create_asgi_app`(srcdir, *[, baseurl, ...])	Create an ASGI application for a site source directory.
`publish`(srcdir, outdir, baseurl, *[, host_static, ...])	Render a site source directory into static output files.
`serve`(srcdir, *[, host, port, baseurl, ...])	Run a development server for a site source directory.

Package Contents¶

httk.serve.web.create_asgi_app(srcdir, *, baseurl=None, compatibility_mode=False, config_name='config', debug=False, table_token_secret=None)[source]¶

Create an ASGI application for a site source directory.

Parameters:

srcdir (str | pathlib.Path) – Site source directory.
baseurl (str | None) – Optional site base URL used when building links.
compatibility_mode (bool) – Whether to use legacy site conventions.
config_name (str) – Configuration module name.
debug (bool) – Whether to enable Starlette debug responses.
table_token_secret (str | bytes | None) – Secret used to authenticate table continuation tokens.

Returns:

Configured serving application.

Return type:

httk.serve.http.ServeApp

httk.serve.web.publish(srcdir, outdir, baseurl, *, host_static=None, compatibility_mode=False, config_name='config', use_urls_without_ext=None)[source]¶

Render a site source directory into static output files.

Parameters:

srcdir (str | pathlib.Path) – Site source directory.
outdir (str | pathlib.Path) – Destination directory for published files.
baseurl (str) – Site base URL used when building links.
host_static (str | None) – Optional host URL for static assets.
compatibility_mode (bool) – Whether to use legacy site conventions.
config_name (str) – Configuration module name.
use_urls_without_ext (bool | None) – Whether published page links omit extensions.

Returns:

Report of files written and rendering warnings.

Return type:

httk.serve.web.model.page.PublishReport

httk.serve.web.serve(srcdir, *, host='127.0.0.1', port=8080, baseurl=None, compatibility_mode=False, config_name='config', debug=False, table_token_secret=None)[source]¶

Run a development server for a site source directory.

Parameters:

srcdir (str | pathlib.Path) – Site source directory.
host (str) – Interface on which to listen.
port (int) – TCP port on which to listen.
baseurl (str | None) – Optional site base URL used when building links.
compatibility_mode (bool) – Whether to use legacy site conventions.
config_name (str) – Configuration module name.
debug (bool) – Whether to enable Starlette debug responses.
table_token_secret (str | bytes | None) – Secret used to authenticate table continuation tokens.

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

widget_id: str¶

query: collections.abc.Mapping[str, str]¶

page: collections.abc.Mapping[str, object]¶

global_data: collections.abc.Mapping[str, object]¶

url_for(route, *, query=None)[source]¶

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

Parameters:

route (str) – Relative site route to link to.
query (collections.abc.Mapping[str, str] | None) – Optional string query values.

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.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¶

label: str¶

align: str | None = None¶

class_name: str | None = None¶

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.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]¶

columns: tuple[TableColumn, Ellipsis]¶

next_cursor: str | None = None¶

previous_cursor: str | None = None¶

total: int | None = None¶

revision: str | None = None¶

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:

rows (collections.abc.Iterable[collections.abc.Mapping[str, object]]) – Presentation-only row mappings.
columns (collections.abc.Iterable[TableColumn | str | collections.abc.Mapping[str, object]]) – Column declarations.
next_cursor (str | None) – Opaque cursor for the next page.
previous_cursor (str | None) – Opaque cursor for the previous page.
total (int | None) – Optional exact total row count.
revision (str | None) – Optional provider revision for stable pagination.

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

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

cursor: str | None = None¶

revision: str | None = None¶

httk.serve.web.SITE_RESOURCES_KEY = 'httk_serve_resources'[source]¶: Stable global_data key through which site startup code gets resources.

class httk.serve.web.SiteResources[source]¶

Callbacks owned by one httk.serve.web.engine.site_engine.SiteEngine.

Site functions/init.py code can obtain this object from global_data[SITE_RESOURCES_KEY] and call register() for every persistent resource it opens. Callbacks run in reverse registration order when the httk.serve.web.engine.site_engine.SiteEngine closes. Closing is idempotent, so ASGI lifespan shutdown and an enclosing helper may both safely close the same engine.

property closed: bool¶

Whether cleanup has started for this registry.

register(callback)[source]¶

Registration after close is a programming error: the callback could no longer be guaranteed to run.

close()[source]¶

Run pending callbacks in LIFO order exactly once.

Every callback gets a chance to run. If cleanup fails, the first exception is re-raised after the remaining callbacks have executed; additional failures are attached as notes for diagnosis.