Cheat sheet - websockets 12.0 documentation
Description: Server: Write a coroutine that handles a single connection. It receives a WebSocket protocol instance and the URI path in argument.- Call recv() and send() to receive and send messages at any time....

Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Cheat sheet

## Server

- Write a coroutine that handles a single connection. It receives a WebSocket protocol instance and the URI path in argument.

  - Call `recv()` and `send()` to receive and send messages at any time.

  - When `recv()` or `send()` raises `ConnectionClosed`, clean up and exit. If you started other `asyncio.Task`, terminate them before exiting.

  - If you aren’t awaiting `recv()`, consider awaiting `wait_closed()` to detect quickly when the connection is closed.

  - You may `ping()` or `pong()` if you wish but it isn’t needed in general.

- Create a server with `serve()` which is similar to asyncio’s `create_server()`. You can also use it as an asynchronous context manager.

  - The server takes care of establishing connections, then lets the handler execute the application logic, and finally closes the connection after the handler exits normally or with an exception.

  - For advanced customization, you may subclass `WebSocketServerProtocol` and pass either this subclass or a factory function as the `create_protocol` argument.

## Client

- Create a client with `connect()` which is similar to asyncio’s `create_connection()`. You can also use it as an asynchronous context manager.

  - For advanced customization, you may subclass `WebSocketClientProtocol` and pass either this subclass or a factory function as the `create_protocol` argument.

- Call `recv()` and `send()` to receive and send messages at any time.

- You may `ping()` or `pong()` if you wish but it isn’t needed in general.

- If you aren’t using `connect()` as a context manager, call `close()` to terminate the connection.

## Debugging

If you don’t understand what websockets is doing, enable logging:

    import logging
    logger = logging.getLogger('websockets')
    logger.setLevel(logging.DEBUG)
    logger.addHandler(logging.StreamHandler())

The logs contain:

- Exceptions in the connection handler at the `ERROR` level

- Exceptions in the opening or closing handshake at the `INFO` level

- All frames at the `DEBUG` level — this can be very verbose

If you’re new to `asyncio`, you will certainly encounter issues that are related to asynchronous programming in general rather than to websockets in particular. Fortunately Python’s official documentation provides advice to develop with asyncio. Check it out: it’s invaluable!