The Request Object

Ushka provides a Request object that is automatically injected into your view functions, giving you access to all the information about the incoming HTTP request.

To use it, simply add a parameter to your view function with the Request type hint.

from ushka.http import Request

async def get_index(request: Request):
    # now you can use the request object
    ...

The Request object has several useful properties and methods.

Headers

You can access request headers via the .headers property, which returns a dictionary-like object.

async def get_index(request: Request):
    user_agent = request.headers.get("user-agent")
    return {"message": f"You are using {user_agent}"}

Query Parameters

Query parameters (the part of the URL after ?) are available via the .query property.

If a URL is /search?q=ushka&page=2, you can access the parameters like this:

async def get_search(request: Request):
    search_term = request.query.get("q")
    page = request.query.get("page", 1) # You can provide a default value
    return {"searching_for": search_term, "on_page": page}

Request Body

Ushka provides several async methods to read the request body, which you must await.

Reading JSON

If you're building an API that receives JSON, you can use request.json().

async def post_users(request: Request):
    data = await request.json()
    username = data.get("username")
    # ... create user ...
    return {"status": "created", "username": username}

Reading Form Data

For standard HTML form submissions (application/x-www-form-urlencoded or multipart/form-data), use request.form().

async def post_login(request: Request):
    form_data = await request.form()
    email = form_data.get("email")
    password = form_data.get("password")
    # ... process login ...
    return {"status": "logged in"}

Reading Raw Body

To get the raw, unprocessed request body as bytes, use request.body().

async def post_webhook(request: Request):
    raw_body = await request.body()
    # ... process raw bytes ...
    return {"status": "received"}

Uploading Files

When a form is submitted with multipart/form-data, you can access uploaded files with request.files(). This method must be awaited and returns a dictionary where keys are the form field names and values are file objects.

The file objects are SpooledTemporaryFile instances, which means small files are kept in memory and larger ones are streamed to disk automatically.

async def post_upload(request: Request):
    files = await request.files()
    uploaded_file = files.get("my_file")

    if uploaded_file:
        # You can read the content
        content = uploaded_file["file"].read()

        # Save it to a permanent location
        with open(f"/path/to/save/{uploaded_file['filename']}", "wb") as f:
            f.write(content)

        return {"status": "file uploaded", "filename": uploaded_file["filename"]}

    return {"status": "no file received"}

Cookies & Sessions

Ushka provides easy access to cookies and sessions.

• Cookies: Access via request.cookies, a dictionary-like object. You can set cookies here as well, and they will be sent with the response.
• Sessions: Access via request.session, a dictionary-like object. Session data is stored in a secure, signed cookie on the client-side.

See the dedicated documentation for more details.