Skip to main content

Response & Redirect

Handlers return values that OxAPY converts into Response objects. The Response class gives you full control over body, status, and headers.

Response​

Constructor​

Response(body, status: Status = Status.OK, content_type: str = "application/json")
  • body — a string, bytes, or JSON-serializable object
  • status — a Status member, defaults to OK
  • content_type — the Content-Type header, defaults to "application/json"
from oxapy import Response, Status

Response({"message": "Success"}) # JSON
Response("Hello", content_type="text/plain") # raw text
Response("Not found", status=Status.NOT_FOUND) # 404, raw text body
Response(b"\x89PNG...", content_type="image/png") # raw bytes
note

String and bytes bodies are sent raw without JSON encoding, regardless of content type. Only objects that are not strings or bytes (such as dictionaries) are serialized with orjson. Use content_type="text/plain" when returning plain text so clients receive the appropriate MIME type.

Properties​

PropertyTypeDescription
statusStatusThe response status; settable
bodystrThe response body as a UTF-8 string
headerslist[tuple[str, str]]Headers as key-value tuples

Methods​

insert_header​

insert_header(key: str, value: str) -> None

Adds or replaces a header.

response.insert_header("Cache-Control", "no-cache")

append_header​

append_header(key: str, value: str) -> None

Appends a value to a repeatable header such as Set-Cookie.

response.append_header("Set-Cookie", "sessionid=abc123")
response.append_header("Set-Cookie", "theme=dark")
set_cookie(
name: str,
value: str,
max_age: int = 3600,
path: str = "/",
domain: str = "",
httponly: bool = True,
secure: bool = True,
samesite: str = "Lax",
) -> None

Adds a cookie to the response via the Set-Cookie header. If a Set-Cookie header already exists the new cookie is appended; otherwise a new header is inserted.

ParameterDefaultDescription
name—The cookie name
value—The cookie value
max_age3600Max-Age in seconds
path"/"Path attribute
domain""Domain attribute (omitted if empty)
httponlyTrueHttpOnly flag
secureTrueSecure flag
samesite"Lax"SameSite attribute
response.set_cookie("session", "abc123", max_age=3600, httponly=True, secure=True)
response.set_cookie("theme", "dark", max_age=86400)

Redirect​

Constructor​

Redirect(location: str)

A Response subclass that issues a 301 Moved Permanently redirect.

from oxapy import Redirect, get


@get("/old")
def old(request):
return Redirect("/new")

Handler return values​

The server converts handler results with convert_to_response:

Return valueResult
ResponseUsed as-is
strtext/plain response
dict / JSON-serializable objectJSON response
StatusJSON response with an empty body and that status
(str, Status)text/plain body with the given status
(obj, Status)JSON body with the given status

Anything else raises a ValueError.

FileStreaming​

Constructor​

FileStreaming(path: str, buf_size: int = 8192, status: Status = Status.OK, content_type: str = "application/octet-stream")

Streams a file in chunks for large files without loading the entire file into memory.

ParameterDefaultDescription
path—Path to the file
buf_size8192Read buffer size in bytes
statusStatus.OKResponse status code
content_type"application/octet-stream"The Content-Type header
from oxapy import FileStreaming

@get("/download")
def download(request):
return FileStreaming("report.pdf", content_type="application/pdf")

See the File Streaming guide for details.