Getting Started

Installation

This library supports Python ≥3.5. The easiest installation method is to use PyPI.

$ pip3 install trio-websocket

You can also install from source. Visit the project’s GitHub page, where you can clone the repository or download a Zip file. Change into the project directory and run the following command.

$ pip3 install .

If you want to contribute to development of the library, also see Developer Installation.

Client Example

This example briefly demonstrates how to create a WebSocket client.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import trio
from trio_websocket import open_websocket_url


async def main():
    try:
        async with open_websocket_url('wss://localhost/foo') as ws:
            await ws.send_message('hello world!')
            message = await ws.get_message()
            logging.info('Received message: %s', message)
    except OSError as ose:
        logging.error('Connection attempt failed: %s', ose)

trio.run(main)

The function open_websocket_url() is a context manager that automatically connects and performs the WebSocket handshake before entering the block. This ensures that the connection is usable before ws.send_message(…) is called. The context manager yields a WebSocketConnection instance that is used to send and receive messages. The context manager also closes the connection before exiting the block.

For more details and examples, see Clients.

Server Example

This example briefly demonstrates how to create a WebSocket server. This server is an echo server, i.e. it responds to each incoming message by sending back an identical message.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import trio
from trio_websocket import serve_websocket, ConnectionClosed

async def echo_server(request):
    ws = await request.accept()
    while True:
        try:
            message = await ws.get_message()
            await ws.send_message(message)
        except ConnectionClosed:
            break

async def main():
    await serve_websocket(echo_server, '127.0.0.1', 8000, ssl_context=None)

trio.run(main)

The function serve_websocket() requires a function that can handle each incoming connection. This handler function receives a WebSocketRequest object that the server can use to inspect the client’s handshake. Next, the server accepts the request in order to complete the handshake and receive a WebSocketConnection instance that can be used to send and receive messages.

For more details and examples, see Servers.