Responses Reference

This page documents Quater response conversion and explicit response classes.

Prerequisites

Read Public API. Most handlers can return plain Python values; use response classes when you need status, headers, redirects, or streams.

from quater import JSONResponse, RedirectResponse, Response, StreamResponse

Automatic Return Values

Handler returns	Quater sends
dict, list, tuple, dataclass, msgspec.Struct	JSONResponse
str	TextResponse
bytes, bytearray, memoryview	BytesResponse
None	EmptyResponse(status_code=204)
Response instance	Sent as-is

If Quater cannot convert the value, it raises ResponseConversionError and returns a 500 Internal Server Error.

Response

Added in 0.1.0a1.

Response(
    body: bytes = b"",
    *,
    status_code: int = 200,
    headers: HeaderItems | Mapping[str, str] | None = None,
    content_type: str | None = None,
) -> None

Parameter	Type	Default	Description
body	bytes	b""	Raw response body.
status_code	int	200	HTTP status code.
headers	HeaderItems | Mapping[str, str] | None	None	Response headers.
content_type	str | None	None	Content type added when no header exists.

JSONResponse

JSONResponse(content: object, *, status_code: int = 200, headers: HeaderItems | Mapping[str, str] | None = None)

Serializes content with Quater's msgspec JSON encoder.

TextResponse

TextResponse(
    content: str,
    *,
    status_code: int = 200,
    headers: HeaderItems | Mapping[str, str] | None = None,
    content_type: str = "text/plain; charset=utf-8",
)

HTMLResponse

HTMLResponse(content: str, *, status_code: int = 200, headers: HeaderItems | Mapping[str, str] | None = None)

Sets content-type: text/html; charset=utf-8.

BytesResponse

BytesResponse(
    content: bytes | bytearray | memoryview,
    *,
    status_code: int = 200,
    headers: HeaderItems | Mapping[str, str] | None = None,
    content_type: str = "application/octet-stream",
)

StreamResponse

StreamResponse(
    body_iterator: AsyncIterable[bytes],
    *,
    status_code: int = 200,
    headers: HeaderItems | Mapping[str, str] | None = None,
    content_type: str = "application/octet-stream",
)

Use this for async byte streams. Resource finalizers stay attached until the adapter finishes consuming the stream.

RedirectResponse

RedirectResponse(
    location: str,
    *,
    status_code: int = 307,
    headers: HeaderItems | Mapping[str, str] | None = None,
)

Default 307 preserves the HTTP method.

EmptyResponse

EmptyResponse(*, status_code: int = 204, headers: HeaderItems | Mapping[str, str] | None = None)

Cookie helpers

Both helpers are available on every response class.

set_cookie

response.set_cookie(
    key: str,
    value: str = "",
    *,
    max_age: int | None = None,
    expires: int | None = None,
    path: str | None = "/",
    domain: str | None = None,
    secure: bool = False,
    httponly: bool = False,
    samesite: Literal["lax", "strict", "none"] | None = "lax",
) -> None

Parameter	Type	Default	Description
key	str	—	Cookie name. Must be a valid RFC 6265 token.
value	str	""	Cookie value. Must be a valid RFC 6265 cookie-octet string.
max_age	int | None	None	Max age in seconds.
expires	int | None	None	Expiry as a Unix timestamp.
path	str | None	"/"	Cookie path.
domain	str | None	None	Cookie domain.
secure	bool	False	Set the Secure flag.
httponly	bool	False	Set the HttpOnly flag.
samesite	Literal["lax", "strict", "none"] | None	"lax"	SameSite policy. "none" requires secure=True.

delete_cookie

response.delete_cookie(
    key: str,
    *,
    path: str | None = "/",
    domain: str | None = None,
    secure: bool = False,
    httponly: bool = False,
    samesite: Literal["lax", "strict", "none"] | None = "lax",
) -> None

Parameter	Type	Default	Description
key	str	—	Cookie name to delete.
path	str | None	"/"	Must match the path used when the cookie was set.
domain	str | None	None	Must match the domain used when the cookie was set.
secure	bool	False	Required for __Secure- and __Host- prefixed cookies.
httponly	bool	False	Set the HttpOnly flag.
samesite	Literal["lax", "strict", "none"] | None	"lax"	Required when the deletion response is sent cross-site. "none" requires secure=True.

Complete Example

from quater import JSONResponse, Quater, RedirectResponse

app = Quater()


@app.post("/orders")
async def create_order() -> JSONResponse:
    return JSONResponse({"id": "ord_1001"}, status_code=201)


@app.get("/orders/latest")
async def latest_order() -> RedirectResponse:
    return RedirectResponse("/orders/ord_1001")

Expected create response:

{
  "id": "ord_1001"
}

What Can Go Wrong

Cannot convert 'set' into a response : Return a supported value or create a Response explicitly.

Invalid response header name : Header names must be valid HTTP token names.

Invalid response header value : Header values cannot contain unsafe control characters.

Also See

• Public API: when to use explicit responses.
• Testing: stream response tests.
• Request Reference: header item type used by responses.