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 objectstatus— aStatusmember, defaults toOKcontent_type— theContent-Typeheader, 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
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
| Property | Type | Description |
|---|---|---|
status | Status | The response status; settable |
body | str | The response body as a UTF-8 string |
headers | list[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
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.
| Parameter | Default | Description |
|---|---|---|
name | — | The cookie name |
value | — | The cookie value |
max_age | 3600 | Max-Age in seconds |
path | "/" | Path attribute |
domain | "" | Domain attribute (omitted if empty) |
httponly | True | HttpOnly flag |
secure | True | Secure 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 value | Result |
|---|---|
Response | Used as-is |
str | text/plain response |
dict / JSON-serializable object | JSON response |
Status | JSON 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.
| Parameter | Default | Description |
|---|---|---|
path | — | Path to the file |
buf_size | 8192 | Read buffer size in bytes |
status | Status.OK | Response 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.
Related
- Responses guide — examples and return types
- Status — the status code enum