Routes

Routes with decorators

The most common and convenient way to create routes in Flama is by using decorators directly on your asynchronous handler functions. The main application instance (typically named app) provides these decorators.

• @app.route(path, methods=["METHOD"], ...): This is the fundamental route decorator.

  • path: A string defining the URL path for the route (e.g., "/items/", "/users/{user_id}").
  • methods: A list of HTTP methods this route responds to (e.g., ["GET"], ["POST"], ["GET", "POST"]). If omitted, it typically defaults to ["GET"].
  • Other optional parameters include name (to refer to the route by name, useful for URL generation) and include_in_schema (to control its visibility in the auto-generated OpenAPI schema).

• Shorthand decorators: For convenience, Flama provides shorthand decorators for common HTTP methods:

  • @app.get(path, ...)
  • @app.post(path, ...)
  • @app.put(path, ...)
  • @app.delete(path, ...)
  • @app.patch(path, ...)
  • @app.options(path, ...)
  • @app.head(path, ...)

  These are equivalent to using @app.route() with the corresponding method specified.

  1

  2

  3

  @app.get("/my-data/")async def fetch_my_data():    return {"data": "sample"}

• Path parameters and type conversion: Routes can include path parameters, which capture segments of the URL. These are defined using curly braces {}. Flama supports type conversion for these parameters directly in the path string.

  • "/items/{item_name:str}": Captures item_name as a string (default if no type is specified).
  • "/items/{item_id:int}": Captures item_id and converts it to an integer.
  • Other supported types include float, and uuid. The converted path parameters are then passed as arguments with the same name to your handler function.
  1

  2

  3

  @app.get("/product/{product_id:int}/")async def get_product(product_id: int): # product_id will be an integer    return {"id": product_id, "name": f"Product {product_id}"}

Routes added programmatically

Besides decorators, you can also add routes to your application programmatically using the app.add_route() method.

• app.add_route(path, endpoint, methods=["METHOD"], name=None, include_in_schema=True):

  • path: The URL path string.
  • endpoint: The asynchronous handler function to be called for this route.
  • methods, name, include_in_schema: Same as for the @app.route() decorator.

This method is useful when generating routes dynamically or when the decorator syntax is less convenient.

async def custom_handler():    return {"message": "Handled manually"}
app.add_route("/manual-endpoint/", custom_handler, methods=["GET"])

Defining WebSocket Routes with Decorators

The primary way to define WebSocket routes is using the @app.websocket_route() decorator:

• @app.websocket_route(path, name=None):

  • path: A string defining the URL path for the WebSocket connection (e.g., "/ws", "/chat/{room_id}").
  • name: An optional name for the WebSocket route.

  The handler function for a WebSocket route must accept a single argument, which will be an instance of flama.websockets.WebSocket.

  1

  2

  3

  4

  5

  6

  7

  8

  9

  10

  11

  12

  13

  14

  from flama import websockets
  @app.websocket_route("/ws-echo")async def websocket_echo(websocket: websockets.WebSocket):    await websocket.accept()    try:        while True:            data = await websocket.receive_text()            await websocket.send_text(f"Echo: {data}")    except websockets.WebSocketDisconnect:        # Client disconnected        pass    else:        await websocket.close()

WebSocket Routes added programmatically

You can also add WebSocket routes using app.add_websocket_route():

• app.add_websocket_route(path, endpoint, name=None):

  • path: The URL path string.
  • endpoint: The asynchronous WebSocket handler function (must accept a flama.websockets.WebSocket argument).
  • name: An optional name.
  1

  2

  3

  4

  5

  6

  async def my_websocket_handler(websocket: flama.websockets.WebSocket):    await websocket.accept()    await websocket.send_text("Connected to manual websocket route!")    await websocket.close()
  app.add_websocket_route("/manual-ws/", my_websocket_handler)

WebSocket Communication Flow

Within a WebSocket handler, you typically:

1. Accept the connection: await websocket.accept() (handled by async with websocket: if used).
2. Communicate: Enter a loop to send and receive messages:
   • Receive messages: await websocket.receive_text(), await websocket.receive_bytes(), await websocket.receive_json().
   • Send messages: await websocket.send_text(...), await websocket.send_bytes(...), await websocket.send_json(...).
3. Handle Disconnects: Catch flama.websockets.WebSocketDisconnect (from Starlette) to manage client disconnections gracefully.
4. Close the connection: await websocket.close(code=1000) (also handled by async with websocket:).