Skip to content

Responses

What a handler returns: a Response, made directly or with its shortcuts (Response.json(), Response.text()...). See Requests and responses.

Response 

Response(body: str | bytes = b'', *, status: int = 200, headers: HeaderItems = ())

An HTTP response; a str body is encoded to UTF-8, so body is bytes.

Guide: https://3d3n-pyc.github.io/korvex/requests-and-responses/#responses

text classmethod 

text(text: str, *, status: int = 200, headers: HeaderItems = ()) -> Response

A text/plain response (unless headers sets Content-Type).

json classmethod 

json(data: Any, *, status: int = 200, headers: HeaderItems = ()) -> Response

An application/json response (unless headers sets Content-Type); data is anything json.dumps takes.

redirect classmethod 

redirect(location: str, *, status: int = 302, headers: HeaderItems = ()) -> Response

An empty redirect to location.

set_cookie(name: str, value: str, *, max_age: Optional[int] = None, path: str = '/', domain: Optional[str] = None, secure: bool = False, httponly: bool = False, samesite: Optional[Literal['lax', 'strict', 'none']] = 'lax') -> None

Adds a Set-Cookie header; max_age is in seconds (none: until the browser closes).

delete_cookie(name: str, *, path: str = '/', domain: Optional[str] = None) -> None

Tells the browser to remove a cookie (same path and domain as when set).

stream classmethod 

stream(chunks: Chunks, *, status: int = 200, headers: HeaderItems = ()) -> StreamingResponse

A response sent piece by piece, from a sync or async iterable of bytes or str.

sse classmethod 

sse(events: Union[Iterable[Any], AsyncIterable[Any]], *, ping: float = 15.0, status: int = 200, headers: HeaderItems = ()) -> StreamingResponse

A Server-Sent Events stream, for the browser's EventSource.

Args: events: A sync or async iterable of ServerSentEvent, or of plain values (sent as the data of an event). ping: Seconds of silence before a keep-alive comment is sent, so proxies keep the connection open. 0 turns it off. Only async iterables get pings: a sync generator is streamed as is. status: The HTTP status. headers: Extra headers; they win over the defaults.

async def clock():
    while True:
        yield ServerSentEvent({"time": time.time()}, event="tick")
        await asyncio.sleep(1)
return Response.sse(clock())

Guide: https://3d3n-pyc.github.io/korvex/requests-and-responses/#server-sent-events

file classmethod 

file(path: str | PathLike[str], *, filename: Optional[str] = None, content_type: Optional[str] = None, status: int = 200, headers: HeaderItems = (), request: Optional[Request] = None) -> StreamingResponse

Sends a file in chunks, type guessed from its name; filename makes it a download.

request: pass it to answer conditional and range requests: 304, 206. Guide: https://3d3n-pyc.github.io/korvex/routes/#static-files

Headers 

Headers(items: HeaderItems = ())

HTTP headers: ordered, case-insensitive, repeated names allowed.

get 

get(name: str, default: str | None = None) -> str | None

The first value for name, or default.

get_all 

get_all(name: str) -> list[str]

Every value for name, in order.

set 

set(name: str, value: str) -> None

Replaces every value for name with value.

remove 

remove(name: str) -> None

Removes every value for name.

add 

add(name: str, value: str) -> None

Adds a value for name, keeping existing ones.

ServerSentEvent 

ServerSentEvent(data: Any = None, *, event: Optional[str] = None, id: Optional[str] = None, retry: Optional[int] = None)

One event of a Server-Sent Events stream.

Send it from a streaming handler; the browser's EventSource receives it.

Args: data: The payload. A str is sent as is; anything else is sent as JSON. None sends no data. event: The event name, a single line. Listeners use it to pick events. id: The event id, a single line without NUL. The browser sends the last one back on reconnect. retry: How many milliseconds the browser waits before reconnecting, an int of 0 or more.

Guide: https://3d3n-pyc.github.io/korvex/requests-and-responses/#server-sent-events

Validate the fields, then build the wire bytes once so errors surface here.

encode 

encode() -> bytes

The event as UTF-8 bytes, ending with a blank line.

StreamingResponse 

StreamingResponse(chunks: Chunks, *, status: int = 200, headers: HeaderItems = ())

A response whose body is sent piece by piece: see Response.stream() and Response.file().

text classmethod 

text(text: str, *, status: int = 200, headers: HeaderItems = ()) -> Response

A text/plain response (unless headers sets Content-Type).

json classmethod 

json(data: Any, *, status: int = 200, headers: HeaderItems = ()) -> Response

An application/json response (unless headers sets Content-Type); data is anything json.dumps takes.

redirect classmethod 

redirect(location: str, *, status: int = 302, headers: HeaderItems = ()) -> Response

An empty redirect to location.

set_cookie(name: str, value: str, *, max_age: Optional[int] = None, path: str = '/', domain: Optional[str] = None, secure: bool = False, httponly: bool = False, samesite: Optional[Literal['lax', 'strict', 'none']] = 'lax') -> None

Adds a Set-Cookie header; max_age is in seconds (none: until the browser closes).

delete_cookie(name: str, *, path: str = '/', domain: Optional[str] = None) -> None

Tells the browser to remove a cookie (same path and domain as when set).

stream classmethod 

stream(chunks: Chunks, *, status: int = 200, headers: HeaderItems = ()) -> StreamingResponse

A response sent piece by piece, from a sync or async iterable of bytes or str.

sse classmethod 

sse(events: Union[Iterable[Any], AsyncIterable[Any]], *, ping: float = 15.0, status: int = 200, headers: HeaderItems = ()) -> StreamingResponse

A Server-Sent Events stream, for the browser's EventSource.

Args: events: A sync or async iterable of ServerSentEvent, or of plain values (sent as the data of an event). ping: Seconds of silence before a keep-alive comment is sent, so proxies keep the connection open. 0 turns it off. Only async iterables get pings: a sync generator is streamed as is. status: The HTTP status. headers: Extra headers; they win over the defaults.

async def clock():
    while True:
        yield ServerSentEvent({"time": time.time()}, event="tick")
        await asyncio.sleep(1)
return Response.sse(clock())

Guide: https://3d3n-pyc.github.io/korvex/requests-and-responses/#server-sent-events

file classmethod 

file(path: str | PathLike[str], *, filename: Optional[str] = None, content_type: Optional[str] = None, status: int = 200, headers: HeaderItems = (), request: Optional[Request] = None) -> StreamingResponse

Sends a file in chunks, type guessed from its name; filename makes it a download.

request: pass it to answer conditional and range requests: 304, 206. Guide: https://3d3n-pyc.github.io/korvex/routes/#static-files