What is trio-websockets?

trio-websockets is a library for building WebSocket servers and clients in Python, based on trio, an asynchronous I/O framework.

Currently a work in progress. The status is:

• The client-side works.

• The server-side does not.

History of the library

The code is originally forked from aaugustin’s websockets library for asyncio, with the following changes:

• Rip out all asyncio things, replace with trio.

• Rip out the websocket protocol code, replace with wsproto.

What remains of the original websockets library itself?

• Most of the remaining code seems to be additional error checking around connection state. Rather than a “trio.BrokenStreamError”, you will receive a ConnectionClosed exception when trying to write on a closed connection.

• The same/very similar interface to websockets, which might be slightly more user-friendly than a raw wsproto connection (say, exposing attributes like .subprotocol, which wsproto passes along during the ConnectionEstablished event).

TODO

• Port the server-side.

• Make the examples run.

• Make the tests run.

• Support for curio.

• Cleanup documentation and readme.

• Experiment with a different architecture, using reader/writer tasks.

How to use it

Here’s a client that says “Hello world!”:

#!/usr/bin/env python

import trio
import trio_websockets

async def hello(uri):
    async with trio_websockets.connect(uri) as websocket:
        await websocket.send("Hello world!")

trio.run(hello, 'ws://localhost:8765')

And here’s an echo server (for Python ≥ 3.6):

#!/usr/bin/env python

import trio
import trio_websockets

async def echo(websocket, path):
    async for message in websocket:
        await websocket.send(message)

trio.run(trio_websockets.serve, echo, 'localhost', 8765)

Does that look good? Start here.

What else?

Bug reports, patches and suggestions welcome! Just open an issue or send a pull request.

trio-websockets is released under the BSD license.