Request objects
===============
.. _request-object:
MicroPie provides two request classes: :class:`~micropie.Request` for
HTTP requests and :class:`~micropie.WebSocketRequest` for WebSocket
connections. You access the current request via
:meth:`~micropie.App.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.
.. attribute:: scope
The original ASGI scope for the request.
.. attribute:: method
The HTTP method, such as ``GET`` or ``POST``.
.. attribute:: path_params
A list of positional path parameters. See
:doc:`../tutorial/routing` for details on parameter mapping.
.. attribute:: 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 :meth:`~micropie.Request.query` to obtain
the first value.
.. method:: query(name, default=None)
Return the first value for query parameter *name*, or *default*
if missing.
.. attribute:: 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 :func:`urllib.parse.parse_qs`. This is the raw
mapping used by MicroPie for argument binding.
.. method:: form(name, default=None)
Return the first value for form/body field *name*, or *default*
if missing.
.. attribute:: get_json
The JSON body parsed into a Python object. Only populated when
the request contains valid JSON with content type
``application/json``.
.. 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
(equivalent to :attr:`~micropie.Request.get_json`). If *name* is
provided and the payload is an object, the value for that key is
returned; otherwise *default* is returned.
.. attribute:: session
A ``dict`` for storing per‑client data across requests. See
:doc:`../howto/sessions`.
.. attribute:: 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
:doc:`../tutorial/routing` for information on awaiting file fields.
.. attribute:: 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 :class:`~micropie.Request` and represents a WebSocket
connection request. All attributes of :class:`~micropie.Request`
apply. For WebSocket handlers the request is accessible via
``self.request`` inside the handler or via the context variable.
