Skip to content

Response Classes

Ignyx provides a flexible way to return responses from your route handlers. Whether you want to return a simple dictionary, a custom response object, or a complex file download, Ignyx has you covered.

Overview

Ignyx automatically handles several return types from your handlers: - dict or list: Serialized to JSON. - str: Returned as plain text or HTML. - tuple: Allows returning body, status code, and headers together. - Response: Built-in response classes for more control.

Automated Response Detection

Ignyx is smart about what you return:

  • JSON: If you return a dict or list, Ignyx sets Content-Type: application/json.
  • HTML: If you return a str that starts with < (after stripping whitespace), Ignyx assumes it's HTML and sets Content-Type: text/html.
  • Text: Otherwise, a str is returned as application/json (wrapped string) or you can use PlainTextResponse.

JSONResponse

Use JSONResponse for explicit JSON responses with custom status codes.

from ignyx.responses import JSONResponse

@app.get("/items/{id}")
def read_item(id: int):
    if id == 0:
        return JSONResponse({"error": "Invalid ID"}, status_code=400)
    return {"id": id, "name": "Item"}

HTMLResponse

Return raw HTML content.

from ignyx.responses import HTMLResponse

@app.get("/welcome")
def welcome():
    return HTMLResponse("<h1>Welcome to Ignyx!</h1>")

PlainTextResponse

Return a plain text response.

from ignyx.responses import PlainTextResponse

@app.get("/robots.txt")
def robots():
    return PlainTextResponse("User-agent: *\nDisallow: /")

RedirectResponse

Perform HTTP redirects.

from ignyx.responses import RedirectResponse

@app.get("/old-path")
def old_path():
    return RedirectResponse("/new-path", status_code=301)

FileResponse

Serve files for download. Ignyx handles this efficiently from the Rust core.

from ignyx.responses import FileResponse

@app.get("/download")
def download():
    return FileResponse("path/to/report.pdf", filename="UserReport.pdf")

Note: Large files (>10MB) are currently buffered; streaming support is in development.

Tuple Syntax

For convenience, you can return a tuple to specify status and headers without importing response classes.

@app.get("/simple")
def simple():
    # body, status_code
    return {"ok": True}, 201

@app.post("/custom")
def custom():
    # body, status_code, headers_dict
    return "Created", 201, {"X-Header": "Ignyx"}

Cookies

You can set cookies using the set_cookie method on response objects.

from ignyx.responses import JSONResponse

@app.post("/login")
def login():
    response = JSONResponse({"message": "Logged in"})
    response.set_cookie("session_id", "abc-123", max_age=3600, httponly=True)
    return response

Parameters for set_cookie: - key: Cookie name. - value: Cookie value. - max_age: Lifetime in seconds. - path: Cookie path (default: /). - domain: Cookie domain. - secure: HTTPS only (default: False). - httponly: Prevents JS access (default: False). - samesite: CSRF protection ("Strict", "Lax", or "None").