Module

server.negotiation

Content negotiation — maps return values to Response objects.

The ContentNegotiator inspects the return value from a route handler and produces the appropriate Response. isinstance-based dispatch, no magic, fully predictable.

4Functions

Functions

_minimal_kida_env 0 Environment ▼
Create a bare kida Environment for inline template rendering. Used when no tem…
def _minimal_kida_env() -> Environment

Create a bare kida Environment for inline template rendering.

Used when no template_dir is configured but an InlineTemplate needs to be rendered (prototyping without any file templates).

Returns
Environment
_html_response 2 Response ▼
Build a text/html response with explicit render intent.
def _html_response(body: str, *, intent: str) -> Response
Parameters
Name Type Description
body str
intent str
Returns
Response
negotiate 3 Response | StreamingResp… ▼
Convert a route handler's return value to a Response. Dispatch order: 1. ``Re…
def negotiate(value: Any, *, kida_env: Environment | None = None, request: Request | None = None) -> Response | StreamingResponse | SSEResponse

Convert a route handler's return value to a Response.

Dispatch order:

  1. Response-> pass through
  2. Redirect-> 302 with Location header
  3. Template-> render via kida -> Response
  4. Fragment-> render block via kida -> Response
  5. Page-> Template or Fragment based on request headers
  6. Action-> empty Response + optional HX headers
  7. ValidationError-> Fragment + 422 + optional HX-Retarget
  8. OOB-> primary + hx-swap-oob fragments
  9. Stream-> kida render_stream() -> StreamingResponse 
    (async sources resolved concurrently)
  10. EventStream-> SSEResponse (handler dispatches to SSE)
  11. str-> 200, text/html
  12. bytes-> 200, application/octet-stream
  13. dict / list-> 200, application/json
  14. (value, int)-> negotiate value, override status
  15. (value, int, dict)-> negotiate value, override status + headers
Parameters
Name Type Description
value Any
kida_env Environment | None Default:None
request Request | None Default:None
Returns
Response | StreamingResponse | SSEResponse
_render_layout_page 3 str ▼
Render a LayoutPage through its layout chain. Decides rendering depth based on…
def _render_layout_page(value: LayoutPage, kida_env: Environment, request: Request | None) -> str

Render a LayoutPage through its layout chain.

Decides rendering depth based on request headers:

  • Fragment request (no history restore): render just the named block
  • Full page / history restore: render page block, then wrap with layouts
  • HX-Target present: render at the appropriate layout depth
Parameters
Name Type Description
value LayoutPage
kida_env Environment
request Request | None
Returns
str