Request objects

MicroPie provides two request classes: Request for HTTP requests and WebSocketRequest for WebSocket connections. You access the current request via request() on your application instance or by using the context variable in lower‑level code.

Request class

class Request(scope)

Represents an incoming HTTP request. The scope argument is the ASGI scope dictionary provided by the server. You should not instantiate this class yourself. MicroPie creates one per request and stores it in a context variable.

The helper methods on Request are synchronous. Use request.query(...), request.form(...) and request.json(...) directly, even inside async def handlers. They return values that MicroPie has already parsed for the current request.

scope

The original ASGI scope for the request.

method

The HTTP method, such as GET or POST.

path_params

A list of positional path parameters. See Routing and handlers for details on parameter mapping. You usually do not need this directly because MicroPie binds path parameters into handler arguments first.

query_params

A dict mapping each query parameter to a list of values. This is the raw parsed mapping from the query string. For convenience, use query() to obtain the first value.

Use this raw attribute when repeated query parameters matter:

tags = request.query_params.get("tag", [])

query(name, default=None)

Return the first value for query parameter name, or default if missing.

This is the usual API for optional query-string inputs:

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

Do not await this method.

body_params

A dict mapping form field names to lists of values. For JSON requests, body parameters are derived from the top-level object; for application/x-www-form-urlencoded forms they are parsed using urllib.parse.parse_qs(). This is the raw mapping used by MicroPie for argument binding.

Use this raw attribute when you need all submitted values for a field, or when middleware needs to inspect parsed request fields:

selected = request.body_params.get("choice", [])

form(name, default=None)

Return the first value for form/body field name, or default if missing.

This helper reads from body_params, so it returns the first parsed body value. It is commonly used for HTML form fields, but top-level JSON object keys are also mirrored into body_params for argument binding.

username = request.form("username", "Anonymous")

Do not await this method.

json(name=None, default=None)

Return the parsed JSON payload or a value from a top-level JSON object.

If name is omitted, this method returns the full parsed payload. If name is provided and the payload is an object, the value for that key is returned; otherwise default is returned.

payload = request.json()
username = request.json("username", "Anonymous")

Do not await this method. MicroPie parses JSON before calling the route handler. Invalid JSON requests receive 400 Bad Request.

session

A dict for storing per‑client data across requests. See Managing sessions.

files

A dict of uploaded files for multipart/form-data requests. Each entry is a mapping containing keys filename, content_type and content, where content is an asyncio.Queue yielding file chunks as bytes. See Routing and handlers for information on awaiting file fields.

Unlike query(), form() and json(), file content is streaming data. Read file chunks asynchronously from the content queue.

headers

A case‑insensitive mapping of header names to values, decoded as UTF‑8 with invalid bytes replaced. Header names are lowercased.

WebSocketRequest class

class WebSocketRequest(scope)

Inherits from Request and represents a WebSocket connection request. All attributes of Request apply. For WebSocket handlers the request is accessible via self.request inside the handler or via the context variable.