Tutorial: Websockets

This tutorial will guide you through building the websocket server present in the examples/websocket directory. This is a very simple app that simply echos back all messages received over the websocket.

Running the example

To run the example, in examples/websocket the following should start the server, (see Installation first),

$ export QUART_APP=websocket:app
$ quart run

the websocket is then available at http://localhost:5000/.

1: Structure

Quart by default expects the code to be structured in a certain way in order for templates and static file to be found. This means that you should structure the websocket as follows,

websocket/
websocket/static/
websocket/static/js/
websocket/static/css/
websocket/templates/

doing so will also make your project familiar to others, as you follow the same convention.

2: Installation

It is always best to run python projects with a pipenv, which should be created and activated as follows,

$ cd websocket
$ pipenv install quart

for this websocket we will only need Quart. Now pipenv can be activated,

$ pipenv shell

3: Websockets

Websocket connections allow for continuous two way communication between a client and a server without having to reopen or negotiate a connection. Chat systems and games are two examples with continuous communication that are well suited to websockets.

Quart natively supports websockets, and a simple websocket echo route is,

from quart import websocket

@app.websocket('/ws')
async def ws():
    while True:
        data = await websocket.receive()
        await websocket.send(f"echo {data}")

Quart also makes testing websockets easy, as so,

@pytest.mark.asyncio
async def test_websocket(app):
    test_client = app.test_client()
    data = b'bob'
    async with test_client.websocket('/ws') as test_websocket:
        await test_websocket.send(data)
        result = await test_websocket.receive()
    assert result == data

4: Javascript

To connect to and communicate with a websocket in Javascript a WebSocket object must be used,

var ws = new WebSocket('ws://' + document.domain + ':' + location.port + '/ws');
ws.onmessage = function (event) {
    console.log(event.data);
};

ws.send('bob');

5: Conclusion

The example files contain this entire tutorial and a little more, so they are now worth a read. Hopefully you can now go ahead and create your own apps that use websockets.