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.

8Functions

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: RenderIntent) -> Response
Parameters
Name Type Description
body str
intent RenderIntent
Returns
Response
_fragment_response 1 Response ▼
Build a text/html response for fragment-returning endpoints.
def _fragment_response(body: str) -> Response
Parameters
Name Type Description
body str
Returns
Response
_require_kida_env 2 Environment ▼
Raise ConfigurationError if kida_env is None (template return types need it).
def _require_kida_env(kida_env: Environment | None, return_type: str) -> Environment
Parameters
Name Type Description
kida_env Environment | None
return_type str
Returns
Environment
_with_current_path_in_context 2 Template | Page | Layout… ▼
Return *value* with ``current_path`` merged into context (copy-on-write). Avoi…
def _with_current_path_in_context(value: Template | Page | LayoutPage, request: Request | None) -> Template | Page | LayoutPage

Return value withcurrent_pathmerged into context (copy-on-write).

Avoids mutating a sharedcontextdict when handlers reuse a frozen Template/Page/LayoutPageacross requests.

Template/Page/LayoutPage use custom __init__— construct fresh instances instead ofdataclasses.replace (which does not pass name).

Parameters
Name Type Description
value Template | Page | LayoutPage
request Request | None
Returns
Template | Page | LayoutPage
_render_composition 6 Response ▼
Shared 5-step pipeline: shell updates → plan → execute → serialize → response. …
def _render_composition(composition: PageComposition, request: Request | None, fragment_target_registry: FragmentTargetRegistry | None, kida_env: Environment, validate_blocks: bool, oob_registry: OOBRegistry | None) -> Response

Shared 5-step pipeline: shell updates → plan → execute → serialize → response.

SetsVary: HX-Requestbecause the response varies depending on whether the request is a full-page load or an htmx fragment request. Without this, HTTP caches may serve a cached fragment to a full-page request (or vice versa).

Parameters
Name Type Description
composition PageComposition
request Request | None
fragment_target_registry FragmentTargetRegistry | None
kida_env Environment
validate_blocks bool
oob_registry OOBRegistry | None
Returns
Response
_set_layout_debug_from_plan 2 None ▼
Set layout debug metadata for LayoutDebugMiddleware when config.debug.
def _set_layout_debug_from_plan(plan: Any, request: Request | None) -> None
Parameters
Name Type Description
plan Any
request Request | None
negotiate 6 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, validate_blocks: bool = False, oob_registry: OOBRegistry | None = None, fragment_target_registry: FragmentTargetRegistry | 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. FormAction-> htmx: fragments or HX-Redirect; non-htmx: 303
  4. Template-> render via kida -> Response
  5. Fragment-> render block via kida -> Response
  6. Page-> Template or Fragment based on request headers
  7. Action-> empty Response + optional HX headers
  8. ValidationError-> Fragment + 422 + optional HX-Retarget
  9. OOB-> primary + hx-swap-oob fragments
  10. Stream-> kida render_stream() -> StreamingResponse 
    (async sources resolved concurrently)
  11. TemplateStream-> kida render_stream_async() -> StreamingResponse
  12. Suspense-> shell + deferred OOB blocks -> StreamingResponse 
    (first paint instant, blocks fill in)
  13. EventStream-> SSEResponse (handler dispatches to SSE)
  14. str-> 200, text/html
  15. bytes-> 200, application/octet-stream
  16. dict / list-> 200, application/json
  17. (value, int)-> negotiate value, override status
  18. (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
validate_blocks bool Default:False
oob_registry OOBRegistry | None Default:None
fragment_target_registry FragmentTargetRegistry | None Default:None
Returns
Response | StreamingResponse | SSEResponse