Core objects
Roll
Roll provides an asyncio protocol.
You can subclass it to set your own Protocol, Route, Query, Form, Files, Request, Response and/or Cookies class(es).
See How to subclass Roll itself guide.
Methods
-
route(path: str, methods: list, protocol: str='http', lazy_body: bool='False', **extras: dict): register a route handler. Usually used as a decorator:
@app.route('/path/with/{myvar}') async def my_handler(request, response, myvar): do_something
By default, Roll routing is powered by autoroutes. Check out its documentation to get more details on which placeholders you can use on route paths.
methods
lists the HTTP methods accepted by this handler. If not defined, the handler will accept onlyGET
. When the handler is a class,methods
must not be used, as Roll will extrapolate them from the defined methods on the class itself. See How to use class-based views for an example of class-based view.The
lazy_body
boolean parameter allows you to consume manually the body of theRequest
. It can be handy if you need to check for instance headers prior to load the whole body into RAM (think images upload for instance) or if you plan to accept a streaming incoming request. By default, the body of the request will be fully loaded.Any
extra
passed will be stored on the route payload, and accessible throughrequest.route.payload
.Raise
ValueError
if two URLs with the same name are registred. -
listen(name: str): listen the event
name
.@app.listen('request') def on_request(request, response): do_something
See Events for a list of available events in Roll core.
HttpError
The object to raise when an error must be returned.
Accepts a status
and a message
.
The status
can be either a http.HTTPStatus
instance or an integer.
Request
A container for the result of the parsing on each request.
The default parsing is made by httptools.HttpRequestParser
.
You can use the empty kwargs
dict to attach whatever you want,
especially useful for extensions.
Properties
- url (
bytes
): raw URL as received by Roll - path (
str
): path element of the URL - query_string (
str
): extracted query string - query (
Query
): Query instance with parsed query string - method (
str
): HTTP verb - body (
bytes
): raw body as received by Roll by default. In case you activated thelazy_body
option in the route, you will have to call theload_body()
method before you access it - form (
Form
): a Form instance with multipart or url-encoded key/values parsed - files (
Files
): a Files instance with multipart files parsed - json (
dict
orlist
): body parsed as JSON - content_type (
str
): shortcut to theContent-Type
header - host (
str
): shortcut to theHost
header - referrer (
str
): shortcut to theReferer
header - origin (
str
): shortcut to theOrigin
header - headers (
dict
): HTTP headers normalized in upper case - cookies (
Cookies
): a Cookies instance with request cookies - route (
Route
): a Route instance storing results from URL matching
In case of errors during the parsing of form
, files
or json
,
an HttpError is raised with a 400
(Bad request) status code.
Methods
- load_body: consume request body and load it in memory
- read ->
bytes
: callload_body
and return the loaded body
Custom properties
While Request
cannot accept arbitrary attributes, it's a dict
like object,
which keys are never used by Roll itself, they are dedicated to external use,
for example for session data.
See How to store custom data in the request for an example of use.
Iterating over Request’s data
If you set the lazy_body
parameter to True
in your route, you will be able to iterate over the Request
object itself to access the data (this is what is done under the hood when you load_body()
by the way). Note that it is only relevant to iterate once across the data.
Response
A container for status
, headers
and body
.
Properties
-
status (
http.HTTPStatus
): the response status# you can set the `status` with the HTTP code directly response.status = 204 # same as response.status = http.HTTPStatus.OK
-
headers (
dict
): case sensitive HTTP headers -
cookies (
Cookies
): a Cookies instanceresponse.cookies.set(name='cookie', value='value', path='/some/path')
-
body (
bytes
): raw Response body; by default, Roll expectsbody
to bebytes
. If it's not, there are two cases:- if
body
is an async generator, Roll will serve a chunked response (see How to serve a chunked response) - if it's anything else, Roll will convert it to
str
(by callingstr()
), and then tobytes
(by calling itsencode()
method)
- if
Shortcuts
-
json: takes any python object castable to
json
and set the body and theContent-Type
headerresponse.json = {'some': 'dict'} # Works also with a `list`: response.json = [{'some': 'dict'}, {'another': 'one'}]
-
redirect: takes a
location, status
tuple, and set the Location header and the status accordingly.response.redirect = "https://example.org", 302
Multipart
Responsible of the parsing of multipart encoded request.body
.
Methods
- initialize(content_type: str): returns a tuple
(Form instance, Files instance) filled with data
from subsequent calls to
feed_data
- feed_data(data: bytes): incrementally fills Form and Files objects with bytes from the body
Multidict
Data structure to deal with several values for the same key. Useful for query string parameters or form-like POSTed ones.
Methods
- get(key: str, default=...): returns a single value for the given
key
, raises anHttpError(BAD_REQUEST)
if thekey
is missing and nodefault
is given - list(key: str, default=...): returns the values for the given
key
aslist
, raises anHttpError(BAD_REQUEST)
if thekey
is missing and nodefault
is given
Query
Handy parsing of GET HTTP parameters.
Inherits from Multidict with all the get
/list
goodies.
Methods
- bool(key: str, default=...): same as
get
but try to cast the value asboolean
; raises anHttpError(BAD_REQUEST)
if the value is not castable - int(key: str, default=...): same as
get
but try to cast the value asint
; raises anHttpError(BAD_REQUEST)
if the value is not castable - float(key: str, default=...): same as
get
but try to cast the value asfloat
; raises anHttpError(BAD_REQUEST)
if the value is not castable
Form
Allow to access casted POST parameters from request.body
.
Inherits from Query with all the get
/list
+ casting goodies.
Files
Allow to access POSTed files from request.body
.
Inherits from Multidict with all the get
/list
goodies.
Cookies
A Cookies management class, built on top of biscuits.
Methods
- set(name, value, max_age=None, expires=None, secure=False, httponly=False, path=None, domain=None): set a new cookie
See How to deal with cookies for examples.
Protocol
Responsible of parsing the request and writing the response.
Routes
Responsible for URL-pattern matching. Allows to switch to your own parser. Default routes use autoroutes, please refers to that documentation for available patterns.
Route
A namedtuple to collect matched route data with attributes:
- payload (
dict
): the data received by the@app.route
decorator, contains all handlers plus optionnal custom data. Value isNone
when request path is not found. - vars (
dict
): URL placeholders resolved for the current route.
Websocket
Communication protocol using a socket between a client (usually the browser) and the server (a route endpoint).
See The Websocket Protocol RFC
- recv(): receive the next message (async).
- send(data): send data to the client. Can handle
str
orbytes
arg (async). - close(code: int, reason: str): close the websocket (async).
- ping(data): send a ping/heartbeat packet (async).
This method returns an
asyncio.Future
object. - pong(): send a pong packet in response to a ping (async).
The websocket object can be used as an asynchronous iterator. Using it that way will yield a message at each iteration while keeping the websocket connection alive.
async def myendpoint(request, ws, **params):
async for message in ws:
print(message)