clients.rst

Clients

.. currentmodule:: trio_websocket

Client Tutorial

This page goes into the details of creating a WebSocket client. Let's start by revisiting the :ref:`client-example`.

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)

Note

A more complete example is included in the repository.

As explained in the tutorial, open_websocket_url(…) is a context manager that ensures the connection is properly opened and ready before entering the block. It also ensures that the connection is closed before exiting the block. This library contains two such context managers for creating client connections: one to connect by host and one to connect by URL.

.. autofunction:: open_websocket
    :async-with: ws

.. autofunction:: open_websocket_url
    :async-with: ws

Custom Nursery

The two context managers above create an internal nursery to run background tasks. If you wish to specify your own nursery instead, you should use the the following convenience functions instead.

.. autofunction:: connect_websocket

.. autofunction:: connect_websocket_url

Custom Stream

The WebSocket protocol is defined as an application layer protocol that runs on top of TCP, and the convenience functions described above automatically create those TCP connections. In more obscure use cases, you might want to run the WebSocket protocol on top of some other type of transport protocol. The library includes a convenience function that allows you to wrap any arbitrary Trio stream with a client WebSocket.

.. autofunction:: wrap_client_stream