httk.serve.http.openapi.app

The deliberately small OpenAPI 3.1-to-Starlette adapter.

Attributes

RequestErrorHandler
ExceptionHandler
RequestScope

Exceptions

OpenAPIContractError	Report an unsupported or internally inconsistent OpenAPI contract.
OpenAPIRequestError	Report adapter-generated request parsing or validation failure.

Classes

OpenAPIParameter	Describe one supported string OpenAPI parameter.
OpenAPIOperation	Describe one supported OpenAPI operation.
OpenAPIRequest	Normalized values passed to an OpenAPI operation handler.
OpenAPIResponse	A handler response constrained by the matched OpenAPI operation.

Functions

parse_openapi_operations(document)	Parse the supported OpenAPI 3.1 path subset.
create_openapi_app(contract, operations, *[, ...])	Create a Starlette app from a constrained OpenAPI 3.1 contract.

Module Contents

type httk.serve.http.openapi.app.RequestErrorHandler = Callable[['OpenAPIRequestError'], 'OpenAPIResponse']

type httk.serve.http.openapi.app.ExceptionHandler = Callable[[Exception, 'OpenAPIRequest'], 'OpenAPIResponse | Awaitable[OpenAPIResponse]']

type httk.serve.http.openapi.app.RequestScope = Callable[['OpenAPIRequest'], contextlib.AbstractAsyncContextManager['OperationContext']]

exception httk.serve.http.openapi.app.OpenAPIContractError

Bases: ValueError

Report an unsupported or internally inconsistent OpenAPI contract.

exception httk.serve.http.openapi.app.OpenAPIRequestError(operation, detail, request)

Bases: ValueError

Report adapter-generated request parsing or validation failure.

Parameters:

• operation (OpenAPIOperation) – The matching operation.

• detail (str) – Human-readable request failure detail.

• request (OpenAPIRequest) – Partial normalized request values.

operation

detail

request

class httk.serve.http.openapi.app.OpenAPIParameter

Describe one supported string OpenAPI parameter.

Parameters:

• name – Parameter name as declared by OpenAPI.

• location – path, query, or header.

• required – Whether the parameter must be sent.

• enum – Optional exact set of accepted string values.

name: str

location: str

required: bool

enum: tuple[str, Ellipsis] | None = None

class httk.serve.http.openapi.app.OpenAPIOperation

Describe one supported OpenAPI operation.

Parameters:

• method – Lowercase HTTP method.

• path – OpenAPI path template.

• operation_id – Unique operation identifier.

• parameters – Supported path, query, and header parameter contracts.

• request_schema – Required JSON request schema identifier, if any.

• responses – Exact status, media type, and schema response contracts.

• success_status – The single declared 2xx status, or None when the operation declares zero or more than one.

method: str

path: str

operation_id: str

parameters: tuple[OpenAPIParameter, Ellipsis]

request_schema: str | None

responses: collections.abc.Mapping[int, tuple[tuple[str | None, str | None], Ellipsis]]

success_status: int | None

property success_contracts: tuple[tuple[str | None, str | None], Ellipsis]

Return the media type and schema contracts declared for the success status.

Returns:

The declared (media type, schema id) pairs for success_status, or an empty tuple when there is no single declared success status.

Return type:

tuple[tuple[str | None, str | None], Ellipsis]

response_contracts(status)

Return the media type and schema contracts declared for one status.

Parameters:

status (int) – Exact HTTP status to look up.

Returns:

The declared (media type, schema id) pairs for status, or an empty tuple when the status is not declared.

Return type:

tuple[tuple[str | None, str | None], Ellipsis]

class httk.serve.http.openapi.app.OpenAPIRequest

Normalized values passed to an OpenAPI operation handler.

Parameters:

• operation – Matched OpenAPI operation.

• path_params – Normalized route parameters.

• query – Query parameters, retaining Starlette’s last-value semantics.

• headers – Lowercase HTTP header names and values.

• body – Validated JSON body, or None for bodyless operations.

operation: OpenAPIOperation

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

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

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

body: Any = None

header(name)

Return one request header case-insensitively.

Parameters:

name (str) – Header name.

Returns:

Header value, if sent.

Return type:

str | None

class httk.serve.http.openapi.app.OpenAPIResponse

A handler response constrained by the matched OpenAPI operation.

Parameters:

• status – Exact declared HTTP status, or None to use the matched operation’s declared success status.

• body – Optional JSON-compatible response body.

• media_type – Exact declared media type; inferred only when unambiguous.

• headers – Additional HTTP response headers.

• after_response – Optional zero-argument coroutine callback run once after the response has been sent.

status: int | None = None

body: Any = None

media_type: str | None = None

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

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

httk.serve.http.openapi.app.parse_openapi_operations(document)

Parse the supported OpenAPI 3.1 path subset.

Local references may be used for path items, operations, parameters, request bodies, and responses. Bodies use external JSON Schema references. Supported parameters are path, query, and header parameters with a simple schema.

Parameters:

document (collections.abc.Mapping[str, Any]) – Caller-owned OpenAPI document mapping.

Returns:

Operations in document order.

Raises:

OpenAPIContractError – If the document uses an unsupported construct.

Return type:

tuple[OpenAPIOperation, Ellipsis]

httk.serve.http.openapi.app.create_openapi_app(contract, operations, *, implementation=None, schemas=None, request_error_handler, exception_handlers=None, request_scope=None, scope_names=(), lifespan=None, debug=False, path_converters=None)

Create a Starlette app from a constrained OpenAPI 3.1 contract.

contract accepts either an OpenAPIContract, which already bundles its offline schema registry, or a plain OpenAPI document mapping paired with a separate schemas registry.

Each operations entry is a bare handler callable or an OperationBinding. The framework binds the operation’s declared path, query, and header parameters, the validated request body, and any whole-request injection to the handler’s parameters by name; see operation().

Parameters:

• contract (OpenAPIContract | Mapping[str, Any]) – Parsed contract, or a caller-owned OpenAPI path document.

• operations (Mapping[str, Callable[..., Any] | OperationBinding]) – Operation-id-to-handler mapping.

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

• schemas (httk.serve.http.openapi.schemas.OpenAPISchemaRegistry | None) – Offline JSON Schema registry for external body references. Required and used when contract is a plain mapping; must not be supplied when contract is an OpenAPIContract.

• request_error_handler (RequestErrorHandler) – Converts request parsing or schema errors to a response.

• exception_handlers (collections.abc.Mapping[type[Exception], ExceptionHandler] | None) – Exact protocol exception classes converted to responses.

• request_scope (RequestScope | None) – Optional per-request async context manager entered around each handler call. It populates the OperationContext extras before the handler runs and may set response metadata after it returns; that metadata is folded into the response on normal completion only, never onto an error or adapted-exception response.

• scope_names (collections.abc.Sequence[str]) – Names of the request-scope values the scope may supply, against which each operation’s declared extras are validated.

• lifespan (collections.abc.Callable[[httk.serve.http.apptypes.ServeApp], Any] | None) – Optional Starlette lifespan callable.

• debug (bool) – Whether Starlette debug responses are enabled.

• path_converters (collections.abc.Mapping[str, str] | None) – OpenAPI path parameter to Starlette converter mapping.

Returns:

Mountable Starlette application.

Raises:

OpenAPIContractError – If the operations or the contract are incomplete or unsupported, if a handler cannot satisfy an operation’s declared inputs by name, or if contract and schemas disagree about which schema registry to use.

Return type:

httk.serve.http.apptypes.ServeApp