quickstart.rst (4965B)
1 Quick start 2 =========== 3 4 .. currentmodule:: websockets 5 6 Here are a few examples to get you started quickly with websockets. 7 8 Say "Hello world!" 9 ------------------ 10 11 Here's a WebSocket server. 12 13 It receives a name from the client, sends a greeting, and closes the connection. 14 15 .. literalinclude:: ../../example/quickstart/server.py 16 :caption: server.py 17 :language: python 18 :linenos: 19 20 :func:`~server.serve` executes the connection handler coroutine ``hello()`` 21 once for each WebSocket connection. It closes the WebSocket connection when 22 the handler returns. 23 24 Here's a corresponding WebSocket client. 25 26 It sends a name to the server, receives a greeting, and closes the connection. 27 28 .. literalinclude:: ../../example/quickstart/client.py 29 :caption: client.py 30 :language: python 31 :linenos: 32 33 Using :func:`~client.connect` as an asynchronous context manager ensures the 34 WebSocket connection is closed. 35 36 .. _secure-server-example: 37 38 Encrypt connections 39 ------------------- 40 41 Secure WebSocket connections improve confidentiality and also reliability 42 because they reduce the risk of interference by bad proxies. 43 44 The ``wss`` protocol is to ``ws`` what ``https`` is to ``http``. The 45 connection is encrypted with TLS_ (Transport Layer Security). ``wss`` 46 requires certificates like ``https``. 47 48 .. _TLS: https://developer.mozilla.org/en-US/docs/Web/Security/Transport_Layer_Security 49 50 .. admonition:: TLS vs. SSL 51 :class: tip 52 53 TLS is sometimes referred to as SSL (Secure Sockets Layer). SSL was an 54 earlier encryption protocol; the name stuck. 55 56 Here's how to adapt the server to encrypt connections. You must download 57 :download:`localhost.pem <../../example/quickstart/localhost.pem>` and save it 58 in the same directory as ``server_secure.py``. 59 60 .. literalinclude:: ../../example/quickstart/server_secure.py 61 :caption: server_secure.py 62 :language: python 63 :linenos: 64 65 Here's how to adapt the client similarly. 66 67 .. literalinclude:: ../../example/quickstart/client_secure.py 68 :caption: client_secure.py 69 :language: python 70 :linenos: 71 72 In this example, the client needs a TLS context because the server uses a 73 self-signed certificate. 74 75 When connecting to a secure WebSocket server with a valid certificate — any 76 certificate signed by a CA that your Python installation trusts — you can 77 simply pass ``ssl=True`` to :func:`~client.connect`. 78 79 .. admonition:: Configure the TLS context securely 80 :class: attention 81 82 This example demonstrates the ``ssl`` argument with a TLS certificate shared 83 between the client and the server. This is a simplistic setup. 84 85 Please review the advice and security considerations in the documentation of 86 the :mod:`ssl` module to configure the TLS context securely. 87 88 Connect from a browser 89 ---------------------- 90 91 The WebSocket protocol was invented for the web — as the name says! 92 93 Here's how to connect to a WebSocket server from a browser. 94 95 Run this script in a console: 96 97 .. literalinclude:: ../../example/quickstart/show_time.py 98 :caption: show_time.py 99 :language: python 100 :linenos: 101 102 Save this file as ``show_time.html``: 103 104 .. literalinclude:: ../../example/quickstart/show_time.html 105 :caption: show_time.html 106 :language: html 107 :linenos: 108 109 Save this file as ``show_time.js``: 110 111 .. literalinclude:: ../../example/quickstart/show_time.js 112 :caption: show_time.js 113 :language: js 114 :linenos: 115 116 Then, open ``show_time.html`` in several browsers. Clocks tick irregularly. 117 118 Broadcast messages 119 ------------------ 120 121 Let's change the previous example to send the same timestamps to all browsers, 122 instead of generating independent sequences for each client. 123 124 Stop the previous script if it's still running and run this script in a console: 125 126 .. literalinclude:: ../../example/quickstart/show_time_2.py 127 :caption: show_time_2.py 128 :language: python 129 :linenos: 130 131 Refresh ``show_time.html`` in all browsers. Clocks tick in sync. 132 133 Manage application state 134 ------------------------ 135 136 A WebSocket server can receive events from clients, process them to update the 137 application state, and broadcast the updated state to all connected clients. 138 139 Here's an example where any client can increment or decrement a counter. The 140 concurrency model of :mod:`asyncio` guarantees that updates are serialized. 141 142 Run this script in a console: 143 144 .. literalinclude:: ../../example/quickstart/counter.py 145 :caption: counter.py 146 :language: python 147 :linenos: 148 149 Save this file as ``counter.html``: 150 151 .. literalinclude:: ../../example/quickstart/counter.html 152 :caption: counter.html 153 :language: html 154 :linenos: 155 156 Save this file as ``counter.css``: 157 158 .. literalinclude:: ../../example/quickstart/counter.css 159 :caption: counter.css 160 :language: css 161 :linenos: 162 163 Save this file as ``counter.js``: 164 165 .. literalinclude:: ../../example/quickstart/counter.js 166 :caption: counter.js 167 :language: js 168 :linenos: 169 170 Then open ``counter.html`` file in several browsers and play with [+] and [-].