cheatsheet.rst (3314B)
1 Cheat sheet 2 =========== 3 4 .. currentmodule:: websockets 5 6 Server 7 ------ 8 9 * Write a coroutine that handles a single connection. It receives a WebSocket 10 protocol instance and the URI path in argument. 11 12 * Call :meth:`~legacy.protocol.WebSocketCommonProtocol.recv` and 13 :meth:`~legacy.protocol.WebSocketCommonProtocol.send` to receive and send 14 messages at any time. 15 16 * When :meth:`~legacy.protocol.WebSocketCommonProtocol.recv` or 17 :meth:`~legacy.protocol.WebSocketCommonProtocol.send` raises 18 :exc:`~exceptions.ConnectionClosed`, clean up and exit. If you started 19 other :class:`asyncio.Task`, terminate them before exiting. 20 21 * If you aren't awaiting :meth:`~legacy.protocol.WebSocketCommonProtocol.recv`, 22 consider awaiting :meth:`~legacy.protocol.WebSocketCommonProtocol.wait_closed` 23 to detect quickly when the connection is closed. 24 25 * You may :meth:`~legacy.protocol.WebSocketCommonProtocol.ping` or 26 :meth:`~legacy.protocol.WebSocketCommonProtocol.pong` if you wish but it isn't 27 needed in general. 28 29 * Create a server with :func:`~server.serve` which is similar to asyncio's 30 :meth:`~asyncio.loop.create_server`. You can also use it as an asynchronous 31 context manager. 32 33 * The server takes care of establishing connections, then lets the handler 34 execute the application logic, and finally closes the connection after the 35 handler exits normally or with an exception. 36 37 * For advanced customization, you may subclass 38 :class:`~server.WebSocketServerProtocol` and pass either this subclass or 39 a factory function as the ``create_protocol`` argument. 40 41 Client 42 ------ 43 44 * Create a client with :func:`~client.connect` which is similar to asyncio's 45 :meth:`~asyncio.loop.create_connection`. You can also use it as an 46 asynchronous context manager. 47 48 * For advanced customization, you may subclass 49 :class:`~client.WebSocketClientProtocol` and pass either this subclass or 50 a factory function as the ``create_protocol`` argument. 51 52 * Call :meth:`~legacy.protocol.WebSocketCommonProtocol.recv` and 53 :meth:`~legacy.protocol.WebSocketCommonProtocol.send` to receive and send messages 54 at any time. 55 56 * You may :meth:`~legacy.protocol.WebSocketCommonProtocol.ping` or 57 :meth:`~legacy.protocol.WebSocketCommonProtocol.pong` if you wish but it isn't 58 needed in general. 59 60 * If you aren't using :func:`~client.connect` as a context manager, call 61 :meth:`~legacy.protocol.WebSocketCommonProtocol.close` to terminate the connection. 62 63 .. _debugging: 64 65 Debugging 66 --------- 67 68 If you don't understand what websockets is doing, enable logging:: 69 70 import logging 71 logger = logging.getLogger('websockets') 72 logger.setLevel(logging.DEBUG) 73 logger.addHandler(logging.StreamHandler()) 74 75 The logs contain: 76 77 * Exceptions in the connection handler at the ``ERROR`` level 78 * Exceptions in the opening or closing handshake at the ``INFO`` level 79 * All frames at the ``DEBUG`` level — this can be very verbose 80 81 If you're new to ``asyncio``, you will certainly encounter issues that are 82 related to asynchronous programming in general rather than to websockets in 83 particular. Fortunately Python's official documentation provides advice to 84 `develop with asyncio`_. Check it out: it's invaluable! 85 86 .. _develop with asyncio: https://docs.python.org/3/library/asyncio-dev.html