httk.serve

Provide unified web-serving, application-composition, and OPTIMADE capabilities.

Submodules

• httk.serve.composition
• httk.serve.dsp
• httk.serve.http
• httk.serve.jsondata
• httk.serve.optimade
• httk.serve.web

Attributes

ServeApp	The httk-serve serving application type (a Starlette app; branded so consumers need not import Starlette).
FrozenJsonValue	An immutable JSON value snapshot.
JsonScalar	A JSON scalar -- string, number, boolean, or null.
JsonValue	An arbitrary JSON value modelled with ordinary mutable containers.

Classes

ASGIAppMount

Associate a Starlette application with an explicit absolute path.

Functions

compose_asgi_apps(mounts, *[, root])	Compose Starlette applications at caller-selected URL paths.
freeze_json(value)	Freeze a JSON-compatible value without retaining caller-owned containers.
thaw_json(value)	Return an independent ordinary JSON value from an immutable snapshot.

Package Contents

class httk.serve.ASGIAppMount

Associate a Starlette application with an explicit absolute path.

Parameters:

• path – Canonical absolute URL path, with / reserved for a root fallback.

• app – Starlette application to mount.

The composed application owns the mounted applications for the duration of its lifespan and enters each distinct child’s Starlette lifespan once. Constructing a mount or a composition does not close or otherwise mutate caller-owned applications when validation fails.

path: str

app: starlette.applications.Starlette

httk.serve.compose_asgi_apps(mounts, *, root=None)

Compose Starlette applications at caller-selected URL paths.

More-specific paths are routed before their ancestors regardless of caller order. At application startup, each distinct mounted child is entered in that deterministic route order and is exited in reverse order; a failed startup unwinds children that already started. The returned parent owns lifespan coordination but not application configuration or data.

Parameters:

• mounts (collections.abc.Iterable[ASGIAppMount]) – Service mounts with paths other than /.

• root (ASGIAppMount | None) – Optional ASGIAppMount at / used as the fallback route.

Returns:

Parent Starlette application containing the requested mounts.

Raises:

• TypeError – If a descriptor or application has the wrong type.

• ValueError – If paths are malformed, noncanonical, or duplicated.

Return type:

starlette.applications.Starlette

type httk.serve.ServeApp = Starlette

The httk-serve serving application type (a Starlette app; branded so consumers need not import Starlette).

Annotation-only: this is a type alias, not the Starlette class, so use Starlette itself for isinstance/subclass checks.

type httk.serve.FrozenJsonValue = JsonScalar | tuple['FrozenJsonValue', ...] | Mapping[str, 'FrozenJsonValue']

An immutable JSON value snapshot.

The mapping arm is typed as Mapping so a plain mutable dict satisfies it statically, while freeze_json() guarantees a MappingProxyType at runtime. This static/runtime gap is intentional and is not closed here.

type httk.serve.JsonScalar = str | int | float | bool | None

A JSON scalar – string, number, boolean, or null.

type httk.serve.JsonValue = JsonScalar | list['JsonValue'] | dict[str, 'JsonValue']

An arbitrary JSON value modelled with ordinary mutable containers.

httk.serve.freeze_json(value)

Freeze a JSON-compatible value without retaining caller-owned containers.

Parameters:

value (object) – JSON-compatible value to copy into an immutable representation.

Returns:

An immutable JSON-compatible value.

Raises:

• TypeError – If value is not JSON-compatible.

• ValueError – If a floating-point value is non-finite.

Return type:

FrozenJsonValue

httk.serve.thaw_json(value)

Return an independent ordinary JSON value from an immutable snapshot.

Parameters:

value (FrozenJsonValue) – Immutable JSON-compatible value to copy.

Returns:

Plain JSON-compatible lists and dictionaries.

Return type:

JsonValue