Flaxon 0.3.0 and Teloce-Py 0.3.0 are available on PyPI. Release instructions are maintained on this site; source links identify the framework snapshot. Check version and upgrade guidance.

Framework source · Markdown

Requests

Overview

The Request object provides access to everything sent by the client, including:

  • HTTP method
  • URL
  • Headers
  • Query parameters
  • Path parameters
  • Cookies
  • Body content
  • Form data
  • Uploaded files
  • Client information
  • Request state

A Request instance is automatically injected into route handlers when requested.

Accessing the Request

from flaxon import Flaxon, Request

app = Flaxon("my-app")

@app.get("/")
async def home(request: Request):
    return {
        "method": request.method,
        "path": request.path,
    }

Request Properties

@app.get("/info")
async def info(request: Request):
    return {
        "method": request.method,
        "path": request.path,
        "url": request.url,
        "scheme": request.scheme,
        "host": request.host,
        "client": request.client,
        "http_version": request.http_version,
    }

Common properties:

Property Description
method HTTP method
path Request path
url Full URL
scheme http or https
host Host name
client Client IP address
headers HTTP headers
cookies Cookies
query Query parameters
state Request-local storage

HTTP Headers

Read individual headers:

@app.get("/headers")
async def headers(request: Request):

    return {
        "user_agent": request.headers.get("user-agent"),
        "accept": request.headers.get("accept"),
        "content_type": request.headers.get("content-type"),
    }

Return every header:

@app.get("/all-headers")
async def headers(request: Request):

    return dict(request.headers)

Check for a header:

if "authorization" in request.headers:
    ...

Query Parameters

URL:

/search?q=python&page=2&category=books

Access them:

@app.get("/search")
async def search(request: Request):

    query = request.query.get("q")

    page = request.query.get_int(
        "page",
        1,
    )

    category = request.query.get(
        "category"
    )

    return {
        "query": query,
        "page": page,
        "category": category,
    }

Typed Query Helpers

page = request.query.get_int("page", 1)

price = request.query.get_float("price")

active = request.query.get_bool("active")

tags = request.query.get_list("tag")

Available helpers:

  • get()
  • get_int()
  • get_float()
  • get_bool()
  • get_list()

Path Parameters

@app.get("/users/<int:user_id>")
async def user(user_id: int):

    return {
        "user_id": user_id
    }

Multiple parameters:

@app.get("/users/<int:user_id>/posts/<int:post_id>")
async def post(
    user_id: int,
    post_id: int,
):

    return {
        "user": user_id,
        "post": post_id,
    }

Cookies

Read cookies:

@app.get("/profile")
async def profile(request: Request):

    session = request.cookies.get(
        "session_id"
    )

    theme = request.cookies.get(
        "theme",
        "light",
    )

    return {
        "session": session,
        "theme": theme,
    }

Reading JSON

@app.post("/users")
async def create_user(request: Request):

    data = await request.json()

    return data

Reading Plain Text

@app.post("/text")
async def text(request: Request):

    body = await request.text()

    return {
        "length": len(body)
    }

Reading Raw Bytes

@app.post("/binary")
async def binary(request: Request):

    data = await request.body()

    return {
        "bytes": len(data)
    }

Form Data

@app.post("/contact")
async def contact(request: Request):

    form = await request.form()

    return {
        "name": form.get("name"),
        "email": form.get("email"),
    }

File Uploads

@app.post("/upload")
async def upload(request: Request):

    form = await request.form()

    file = form["file"]

    return {
        "filename": file.filename,
        "content_type": file.content_type,
    }

Automatic Validation

Schemas automatically validate incoming data.

from flaxon.validation import Schema, fields

class CreateUser(Schema):

    name = fields.StrField(
        required=True,
        min_length=2,
    )

    email = fields.EmailField(
        required=True,
    )

    age = fields.IntField(
        minimum=13,
    )

Use the schema:

@app.post("/users")
async def create_user(data: CreateUser):

    return data.to_dict()

Combining Request and Validation

@app.post("/users")
async def create_user(
    request: Request,
    data: CreateUser,
):

    return {
        "ip": request.client,
        "user": data.to_dict(),
    }

Request State

Store data during request processing.

@app.get("/")
async def home(request: Request):

    request.state.user_id = 15

    return {
        "user": request.state.user_id
    }

Middleware:

request.state.start_time = time.time()

Route:

elapsed = time.time() - request.state.start_time

Client Information

@app.get("/client")
async def client(request: Request):

    return {
        "ip": request.client,
        "user_agent": request.headers.get("user-agent"),
    }

Authentication Information

When authentication middleware is enabled:

@app.get("/profile")
async def profile(request: Request):

    user = request.user

    return user.to_dict()

Request Context

Access the current request anywhere in your application.

from flaxon.application.context import get_current_request

request = get_current_request()

Example:

def current_ip():

    request = get_current_request()

    return request.client

Reading Large Bodies

For very large uploads use streaming.

@app.post("/upload")
async def upload(request: Request):

    async for chunk in request.stream():

        process(chunk)

    return {
        "uploaded": True
    }

Streaming avoids loading the entire request into memory.

Complete Example

from flaxon import Flaxon, Request
from flaxon.validation import Schema, fields

app = Flaxon("request-demo")

class CreateUser(Schema):

    username = fields.StrField(required=True)

    email = fields.EmailField(required=True)

@app.get("/users/<int:user_id>")
async def get_user(
    user_id: int,
    request: Request,
):

    return {
        "user_id": user_id,
        "include_posts": request.query.get_bool(
            "posts",
            False,
        ),
        "client": request.client,
    }

@app.post("/users")
async def create_user(
    request: Request,
    data: CreateUser,
):

    return {
        "success": True,
        "user": data.to_dict(),
        "session": request.cookies.get("session_id"),
    }

Best Practices

  • Use schema validation whenever possible.
  • Use typed query helpers instead of manual conversion.
  • Keep request handlers lightweight.
  • Avoid reading the body multiple times.
  • Use streaming for large uploads.
  • Store request-specific data in request.state.
  • Never trust client input without validation.
  • Use HTTPS in production.
  • Protect sensitive endpoints with authentication and authorization.

Use this capability in a full-stack app

Flaxon serves Python APIs and Teloce interfaces in one project. Keep validation, authorization and privileged operations on the server; components call those endpoints and present their results. Follow the full-stack lessons and Teloce integration reference to connect this capability to pages, components and application modules.