httk.serve.web.model¶

Provide configuration, request, result, and error models for web sites.

Submodules¶

Exceptions¶

`FunctionInjectionError`	Represent a failure while injecting a site function result.
`NotFoundError`	Represent a route or site resource that cannot be found.
`WebError`	Represent a handled web failure with an HTTP status code.
`WidgetDiscoveryError`	Report a widget that cannot be discovered or loaded.
`WidgetError`	Base error for a widget invocation with source-aware diagnostics.
`WidgetParseError`	Report a widget invocation that cannot be parsed.
`WidgetRenderingError`	Report a widget that failed while producing output.
`WidgetValidationError`	Report a widget declaration that violates its contract.

Classes¶

`SiteConfig`	Describe the directories and URL policy used by a site engine.
`PageResult`	Carry one rendered page response and its publication metadata.
`PublishReport`	Report files written and warnings collected during publication.
`ResolvedRoute`	Describe how a requested route was resolved.
`HttpRequestContext`	Carry the request values exposed to a rendered site page.

Package Contents¶

class httk.serve.web.model.SiteConfig[source]¶

Describe the directories and URL policy used by a site engine.

Parameters:

srcdir – Absolute or relative site source directory.
content_subdir – Content directory name relative to srcdir.
static_subdir – Static directory name relative to srcdir.
template_subdir – Template directory name relative to srcdir.
functions_subdir – Function directory name relative to srcdir.
widgets_subdir – Widget directory name relative to srcdir.
baseurl – Optional site base URL.
host_static – Optional host URL for static assets.
compatibility_mode – Whether to use legacy site conventions.
config_name – Configuration module name.
publish_use_urls_without_ext – Whether published page links omit extensions.

srcdir: pathlib.Path¶

content_subdir: str = 'content'¶

static_subdir: str = 'static'¶

template_subdir: str = 'templates'¶

functions_subdir: str = 'functions'¶

widgets_subdir: str = 'widgets'¶

baseurl: str | None = None¶

host_static: str | None = None¶

compatibility_mode: bool = False¶

config_name: str = 'config'¶

publish_use_urls_without_ext: bool = True¶

classmethod from_srcdir(srcdir, *, baseurl=None, host_static=None, compatibility_mode=False, config_name='config', publish_use_urls_without_ext=True)[source]¶

Build site configuration from a source directory.

Parameters:

srcdir (str | pathlib.Path) – Site source directory.
baseurl (str | None) – Optional site base URL.
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.
publish_use_urls_without_ext (bool) – Whether published page links omit extensions.

Returns:

Immutable site configuration.

Return type:

Self

property content_dir: pathlib.Path¶

Return the configured content directory.

property static_dir: pathlib.Path¶

Return the configured static directory.

property template_dir: pathlib.Path¶

Return the configured template directory.

property functions_dir: pathlib.Path¶

Return the active site function directory.

property widgets_dir: pathlib.Path¶

Return the configured widget directory.

exception httk.serve.web.model.FunctionInjectionError(message)[source]¶

Bases: WebError

Represent a failure while injecting a site function result.

Parameters:: message (str) – Human-readable failure message.

exception httk.serve.web.model.NotFoundError(message='Not Found')[source]¶

Bases: WebError

Represent a route or site resource that cannot be found.

Parameters:: message (str) – Human-readable not-found message.

exception httk.serve.web.model.WebError(message, *, status_code=500)[source]¶

Bases: Exception

Represent a handled web failure with an HTTP status code.

Parameters:

message (str) – Human-readable failure message.
status_code (int) – HTTP status code associated with the failure.

status_code = 500¶

exception httk.serve.web.model.WidgetDiscoveryError(message, *, source_path=None, line=None, column=None, snippet=None, widget_name=None, widget_id=None, correction=None)[source]¶

Bases: WidgetError

Report a widget that cannot be discovered or loaded.

phase = 'discovery'¶

exception httk.serve.web.model.WidgetError(message, *, source_path=None, line=None, column=None, snippet=None, widget_name=None, widget_id=None, correction=None)[source]¶

Bases: WebError

Base error for a widget invocation with source-aware diagnostics.

phase = 'widget'¶

exception httk.serve.web.model.WidgetParseError(message, *, source_path=None, line=None, column=None, snippet=None, widget_name=None, widget_id=None, correction=None)[source]¶

Bases: WidgetError

Report a widget invocation that cannot be parsed.

phase = 'parse'¶

exception httk.serve.web.model.WidgetRenderingError(message, *, source_path=None, line=None, column=None, snippet=None, widget_name=None, widget_id=None, correction=None)[source]¶

Bases: WidgetError

Report a widget that failed while producing output.

phase = 'rendering'¶

exception httk.serve.web.model.WidgetValidationError(message, *, source_path=None, line=None, column=None, snippet=None, widget_name=None, widget_id=None, correction=None)[source]¶

Bases: WidgetError

Report a widget declaration that violates its contract.

phase = 'validation'¶

class httk.serve.web.model.PageResult[source]¶

Carry one rendered page response and its publication metadata.

Parameters:

status_code – HTTP status code for the rendered page.
content_type – Response content type.
body – Rendered response bytes.
metadata – Page metadata exposed to templates.
warnings – Non-fatal rendering warnings.
assets – Trusted widget assets used by the page.

status_code: int¶

content_type: str¶

body: bytes¶

metadata: dict[str, object]¶

warnings: list[str] = []¶

assets: tuple[httk.serve.web.widgets.core.WidgetAsset, Ellipsis] = ()¶

class httk.serve.web.model.PublishReport[source]¶

Report files written and warnings collected during publication.

Parameters:

written_files – Output files written by publication.
warnings – Non-fatal publication warnings.

written_files: list[pathlib.Path] = []¶

warnings: list[str] = []¶

class httk.serve.web.model.ResolvedRoute[source]¶

Describe how a requested route was resolved.

Parameters:

kind – Resolution kind: static, content, or missing.
route – Normalized route text.
source_path – Matching source path when one exists.

kind: Literal['static', 'content', 'missing']¶

route: str¶

source_path: pathlib.Path | None = None¶

class httk.serve.web.model.HttpRequestContext[source]¶

Carry the request values exposed to a rendered site page.

Parameters:

method – HTTP method.
query – Query-string values.
postvars – Parsed POST values.
headers – Lower-case request headers.

method: str = 'GET'¶

query: dict[str, str]¶

postvars: dict[str, str]¶

headers: dict[str, str]¶