Low Level Server¶

This topic describes aiohttp.web based low level API.

Abstract¶

Sometimes user don’t need high-level concepts introduced in Server: applications, routers, middlewares and signals.

All what is needed is supporting asynchronous callable which accepts a request and returns a response object.

This is done by introducing aiohttp.web.Server class which serves a protocol factory role for asyncio.AbstractEventLoop.create_server() and bridges data stream to web handler and sends result back.

Low level web handler should accept the single BaseRequest parameter and performs one of the following actions:

Return a Response with the whole HTTP body stored in memory.

Create a StreamResponse, send headers by StreamResponse.prepare() call, send data chunks by StreamResponse.write() and return finished response.

Raise HTTPException derived exception (see Exceptions section).

All other exceptions not derived from HTTPException leads to 500 Internal Server Error response.

Initiate and process Web-Socket connection by WebSocketResponse using (see WebSockets).

Run a Basic Low-Level Server¶

The following code demonstrates very trivial usage example:

import asyncio
from aiohttp import web


async def handler(request):
    return web.Response(text="OK")


async def main(loop):
    server = web.Server(handler)
    await loop.create_server(server, "127.0.0.1", 8080)
    print("======= Serving on http://127.0.0.1:8080/ ======")

    # pause here for very long time by serving HTTP requests and
    # waiting for keyboard interruption
    await asyncio.sleep(100*3600)


loop = asyncio.get_event_loop()

try:
    loop.run_until_complete(main(loop))
except KeyboardInterrupt:
    pass
loop.close()

In the snippet we have handler which returns a regular Response with "OK" in BODY.

This handler is processed by server (Server which acts as protocol factory). Network communication is created by loop.create_server call to serve http://127.0.0.1:8080/.

The handler should process every request for every path, e.g. GET, POST, Web-Socket.

The example is very basic: it always return 200 OK response, real life code is much more complex usually.