Sending Responses

Sending a response is a fundamental aspect of every HTTP request. Nexios offers a well-rounded and robust framework designed to handle this process efficiently, ensuring clarity, flexibility, and performance in every interaction.

Basic Example

@app.get("/users")
async def getUsers(request, response):
    return ["John Doe","Jane Smith"]

By default nexios turns JSON-serializable python data-types returned from route handlers as response which are sent to the client as json response

Returning Various Data Types

You can return various data types from your route handlers:

List

@app.get("/users")
async def getUsers(request, response):
    return ["John Doe","Jane Smith"]

String

@app.get("/users")
async def getUsers(request, response):
    return "Hello World"

Dict

@app.get("/users")
async def getUsers(request, response):
    return {"name": "John Doe", "age": 30}

Int

@app.get("/users")
async def getUsers(request, response):
    return 200

Enum

@app.get("/users")
async def getUsers(request, response):
    return StatusCodes.OK

The Response Object

for complex responses you can use the Response object the response object is passed as the second argument to your route handlers

@app.get("/users")
async def getUsers(request, response):
    return response.json(["John Doe","Jane Smith"])

Other Response Types

JSON

@app.get("/users")
async def getUsers(request, response):
    return response.json(["John Doe","Jane Smith"])

HTML

@app.get("/users")
async def getUsers(request, response):
    return response.html("Hello World")

Text

@app.get("/users")
async def getUsers(request, response):
    return response.text("Hello World")

File

@app.get("/users")
async def getUsers(request, response):
    return response.file("path/to/file.txt")

Redirect

@app.get("/users")
async def getUsers(request, response):
    return response.redirect("/users")

Streaming

@app.get("/users")
async def getUsers(request, response):
    async def stream():
        for i in range(10):
            yield f"{i}\n"
    return response.stream(stream())

Sending Status Code

response object has a status method that allows you to set the status code of the response.

@app.get("/users")
async def getUsers(request, response):
    return response.status(200).json(["John Doe","Jane Smith"])

💡 Recommended

For clarity and to leverage the full power of Nexios's response handling, we recommend using the response object to build your responses, especially when you need to set custom headers, cookies, or status codes.

Chainable Responses

You can chain multiple methods together to configure the response before sending it. This makes your code more concise and expressive.

from nexios import NexiosApp

app = NexiosApp()

@app.get("/")
async def home(req, res):
    res.status(200).set_cookie("session_id", "123").json({"message": "Hello, World!"})

In this example, we set the status code, add a cookie, and send a JSON response all in a single, chained statement.

Sending Different Types of Responses using the object directly

Nexios provides several methods for sending different types of responses.

JSON Responses

To send a JSON response, use the .json() method. It automatically sets the Content-Type header to application/json.

@app.get("/users")
async def get_users(req, res):
    users = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
    res.json(users)

HTML Responses

To send an HTML response, use the .html() method. This will set the Content-Type header to text/html.

@app.get("/welcome")
async def welcome(req, res):
    html_content = "<h1>Welcome to our website!</h1>"
    res.html(html_content)

Plain Text Responses

For plain text responses, use the .text() method. The Content-Type will be set to text/plain.

@app.get("/status")
async def status(req, res):
    res.text("Service is running.")

Redirects

To redirect the client to a different URL, use the .redirect() method.

@app.get("/old-path")
async def old_path(req, res):
    res.redirect("/new-path", status_code=301) # Permanent redirect

Customizing the Response

You can customize the response by setting the status code, headers, and cookies.

Setting the Status Code

Use the .status() method to set the HTTP status code.

@app.post("/create-user")
async def create_user(req, res):
    # some logic to create a user
    res.status(201).json({"message": "User created successfully"})

Setting Headers

Use the .set_header() method to add or modify HTTP headers.

@app.get("/data")
async def get_data(req, res):
    res.set_header("Cache-Control", "no-cache").json({"data": "some data"})

Setting Cookies

Use the .set_cookie() method to set a cookie on the client's browser.

@app.post("/login")
async def login(req, res):
    res.set_cookie(
        key="user_token",
        value="secret-token",
        httponly=True,
        max_age=3600 # 1 hour
    ).json({"message": "Logged in"})

File Responses

Nexios allows you to send files as responses using the .file() method. This is useful for serving images, documents, or other static assets.

@app.get("/download-report")
async def download_report(req, res):
    file_path = "path/to/your/report.pdf"
    res.file(file_path, content_disposition_type="attachment")

By setting content_disposition_type="attachment", you prompt the browser to download the file instead of displaying it.

Returning Data Directly

For simple cases, you can return a dict, list, or str directly from your handler. Nexios will automatically convert it into a JSON response.

@app.get("/simple")
async def simple_response(req, res):
    return {"message": "This is a simple response."}

However, for more control over the response, it is recommended to use the Response object and its methods.

💡 Recommended

For clarity and to leverage the full power of Nexios's response handling, we recommend using the res object to build your responses, especially when you need to set custom headers, cookies, or status codes.

Advanced Usage: Response Classes

For more advanced use cases, Nexios allows you to work directly with Response classes. This gives you the ultimate flexibility to control the response sent to the client. You can either use the built-in response classes or create your own.

Using Built-in Response Classes

Instead of using the res object's methods, you can return an instance of a response class directly from your handler. Nexios provides several built-in response classes in the nexios.http.response module.

• JSONResponse
• HTMLResponse
• TextResponse
• RedirectResponse
• FileResponse
• StreamingResponse

Example:

from nexios import NexiosApp
from nexios.http.response import JSONResponse, HTMLResponse

app = NexiosApp()

@app.get("/users-json")
async def get_users_json(req, res):
    users = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
    return JSONResponse(users, status_code=200)

@app.get("/welcome-html")
async def welcome_html(req, res):
    html_content = "<h1>Welcome from a Response class!</h1>"
    return HTMLResponse(html_content)

Creating Custom Response Classes

You can create your own custom response classes by inheriting from nexios.http.response.Response. This is useful when you need to send responses in a format that is not supported out of the box, such as XML.

Example: Creating an XMLResponse class

from nexios import NexiosApp
from nexios.http.response import Response
from dicttoxml import dicttoxml

class XMLResponse(Response):
    media_type = "application/xml"

    def __init__(self, content, *args, **kwargs):
        xml_content = dicttoxml(content)
        super().__init__(content=xml_content, *args, **kwargs)

app = NexiosApp()

@app.get("/data.xml")
async def get_xml_data(req, res):
    data = {"user": {"name": "John Doe", "id": "123"}}
    return XMLResponse(data)

In this example:

1. We create a new XMLResponse class that inherits from nexios.http.response.Response.
2. We set the media_type to application/xml.
3. In the __init__ method, we convert the incoming dict to XML using the dicttoxml library before passing it to the parent class.
4. Finally, we return an instance of our XMLResponse from the route handler.

By creating custom response classes, you can encapsulate response logic and reuse it across your application, leading to cleaner and more maintainable code.