httk.serve.http.openapi.binding

Bind declared OpenAPI operation inputs to plain handler parameters by name.

Classes

OperationBinding	Declare how one operation's declared inputs bind to a handler callable.
OperationContext	Carry per-request values between a request scope and one operation handler.
BoundParameter	Describe where one handler parameter's value is resolved from per request.
BoundOperation	A validated binding of one operation to its resolved handler callable.

Functions

normalize_parameter_name(name)	Normalize an OpenAPI wire parameter name to a Python identifier form.
operation(target, *[, aliases, extras])	Declare an operation binding with optional aliases and request-scope extras.
convert_result(operation_id, result)	Convert a handler return value into a constrained operation response.
bind_operation(operation, entry, *[, implementation, ...])	Validate and bind one operation's declared inputs to its handler by name.

Module Contents

httk.serve.http.openapi.binding.normalize_parameter_name(name)

Normalize an OpenAPI wire parameter name to a Python identifier form.

Hyphens become underscores, camelCase and ACRONYMCase boundaries are split, the result is lowercased, repeated underscores collapse, and leading and trailing underscores are stripped. The returned string is not guaranteed to be a valid identifier; a wire name that does not normalize to one (for example filter[name]) is not auto-bindable and requires an explicit alias.

Parameters:

name (str) – OpenAPI wire parameter name.

Returns:

Normalized handler-parameter name candidate.

Return type:

str

class httk.serve.http.openapi.binding.OperationBinding

Declare how one operation’s declared inputs bind to a handler callable.

Parameters:

• target – Callable implementing the operation. A bound method or module-level function is used directly; a plain function defined on a class is resolved against implementation when the application is created.

• aliases – Wire parameter name to handler parameter name overrides. The reserved wire name body remaps the request body.

• extras – Names of request-scope values this operation consumes.

target: collections.abc.Callable[Ellipsis, Any]

aliases: collections.abc.Mapping[str, str]

extras: tuple[str, Ellipsis] = ()

httk.serve.http.openapi.binding.operation(target, *, aliases=None, extras=())

Declare an operation binding with optional aliases and request-scope extras.

Parameters:

• target (collections.abc.Callable[Ellipsis, Any]) – Callable implementing the operation.

• aliases (collections.abc.Mapping[str, str] | None) – Wire parameter name to handler parameter name overrides.

• extras (collections.abc.Sequence[str]) – Names of request-scope values this operation consumes.

Returns:

The declared operation binding.

Return type:

OperationBinding

class httk.serve.http.openapi.binding.OperationContext

Carry per-request values between a request scope and one operation handler.

The scope populates extras before the handler runs; the framework passes each extra the operation declares to the handler by name. After the handler returns, the scope may set media_type, headers, and after_response, which the framework folds into the response on normal completion only. The context is mutable by design so the scope can both supply inputs and collect response metadata.

Parameters:

• extras – Request-scope values keyed by the extra name each declares.

• media_type – Exact response media type the scope contributes, if any.

• headers – Additional response headers the scope contributes.

• after_response – Zero-argument coroutine callback the scope contributes to run once after the response has been sent, if any.

extras: dict[str, Any]

media_type: str | None = None

headers: dict[str, str]

after_response: httk.serve.http.apptypes.ResponseHook | None = None

class httk.serve.http.openapi.binding.BoundParameter

Describe where one handler parameter’s value is resolved from per request.

Parameters:

• param – Handler parameter name that receives the value.

• kind – Source kind: path, query, header, body, request, or extra.

• key – Lookup key within the source; the wire parameter name (lowercased for headers) for parameter sources, the scope name for extra, and unused for body and request.

param: str

kind: str

key: str

class httk.serve.http.openapi.binding.BoundOperation(operation, target, sources)

A validated binding of one operation to its resolved handler callable.

Parameters:

• operation (httk.serve.http.openapi.app.OpenAPIOperation) – The operation this binding serves.

• target (collections.abc.Callable[Ellipsis, Any]) – Resolved handler callable to invoke.

• sources (collections.abc.Sequence[BoundParameter]) – Per-request sources for the handler’s bound parameters.

property operation_id: str

Return the bound operation’s identifier.

Returns:

The operation id.

Return type:

str

async httk.serve.http.openapi.binding.convert_result(operation_id, result)

Convert a handler return value into a constrained operation response.

An awaitable is awaited first, so both synchronous and asynchronous handlers are supported. None becomes the bodyless success response, a mapping or list becomes a response body, and an OpenAPIResponse is used as is.

Parameters:

• operation_id (str) – Operation identifier used in error messages.

• result (Any) – Raw handler return value or awaitable of one.

Returns:

The constrained operation response.

Raises:

TypeError – If the result is not a supported response value.

Return type:

httk.serve.http.openapi.app.OpenAPIResponse

httk.serve.http.openapi.binding.bind_operation(operation, entry, *, implementation=None, scope_names=())

Validate and bind one operation’s declared inputs to its handler by name.

Parameters:

• operation (httk.serve.http.openapi.app.OpenAPIOperation) – The declared operation to bind.

• entry (collections.abc.Callable[Ellipsis, Any] | OperationBinding) – A bare handler callable, or an OperationBinding.

• implementation (object | None) – Object whose methods resolve class-defined function entries; None uses each entry callable directly.

• scope_names (collections.abc.Collection[str]) – Request-scope value names available to extras.

Returns:

The validated per-request binding.

Raises:

OpenAPIContractError – If the handler cannot satisfy the operation’s declared inputs by name.

Return type:

BoundOperation