Source code
Revision control
Copy as Markdown
Other Tools
Quick start
===========
.. currentmodule:: websockets
Here are a few examples to get you started quickly with websockets.
Say "Hello world!"
------------------
Here's a WebSocket server.
It receives a name from the client, sends a greeting, and closes the connection.
.. literalinclude:: ../../example/quickstart/server.py
:caption: server.py
:language: python
:linenos:
:func:`~server.serve` executes the connection handler coroutine ``hello()``
once for each WebSocket connection. It closes the WebSocket connection when
the handler returns.
Here's a corresponding WebSocket client.
It sends a name to the server, receives a greeting, and closes the connection.
.. literalinclude:: ../../example/quickstart/client.py
:caption: client.py
:language: python
:linenos:
Using :func:`~client.connect` as an asynchronous context manager ensures the
WebSocket connection is closed.
.. _secure-server-example:
Encrypt connections
-------------------
Secure WebSocket connections improve confidentiality and also reliability
because they reduce the risk of interference by bad proxies.
The ``wss`` protocol is to ``ws`` what ``https`` is to ``http``. The
connection is encrypted with TLS_ (Transport Layer Security). ``wss``
requires certificates like ``https``.
.. admonition:: TLS vs. SSL
:class: tip
TLS is sometimes referred to as SSL (Secure Sockets Layer). SSL was an
earlier encryption protocol; the name stuck.
Here's how to adapt the server to encrypt connections. You must download
:download:`localhost.pem <../../example/quickstart/localhost.pem>` and save it
in the same directory as ``server_secure.py``.
.. literalinclude:: ../../example/quickstart/server_secure.py
:caption: server_secure.py
:language: python
:linenos:
Here's how to adapt the client similarly.
.. literalinclude:: ../../example/quickstart/client_secure.py
:caption: client_secure.py
:language: python
:linenos:
In this example, the client needs a TLS context because the server uses a
self-signed certificate.
When connecting to a secure WebSocket server with a valid certificate — any
certificate signed by a CA that your Python installation trusts — you can
simply pass ``ssl=True`` to :func:`~client.connect`.
.. admonition:: Configure the TLS context securely
:class: attention
This example demonstrates the ``ssl`` argument with a TLS certificate shared
between the client and the server. This is a simplistic setup.
Please review the advice and security considerations in the documentation of
the :mod:`ssl` module to configure the TLS context securely.
Connect from a browser
----------------------
The WebSocket protocol was invented for the web — as the name says!
Here's how to connect to a WebSocket server from a browser.
Run this script in a console:
.. literalinclude:: ../../example/quickstart/show_time.py
:caption: show_time.py
:language: python
:linenos:
Save this file as ``show_time.html``:
.. literalinclude:: ../../example/quickstart/show_time.html
:caption: show_time.html
:language: html
:linenos:
Save this file as ``show_time.js``:
.. literalinclude:: ../../example/quickstart/show_time.js
:caption: show_time.js
:language: js
:linenos:
Then, open ``show_time.html`` in several browsers. Clocks tick irregularly.
Broadcast messages
------------------
Let's change the previous example to send the same timestamps to all browsers,
instead of generating independent sequences for each client.
Stop the previous script if it's still running and run this script in a console:
.. literalinclude:: ../../example/quickstart/show_time_2.py
:caption: show_time_2.py
:language: python
:linenos:
Refresh ``show_time.html`` in all browsers. Clocks tick in sync.
Manage application state
------------------------
A WebSocket server can receive events from clients, process them to update the
application state, and broadcast the updated state to all connected clients.
Here's an example where any client can increment or decrement a counter. The
concurrency model of :mod:`asyncio` guarantees that updates are serialized.
Run this script in a console:
.. literalinclude:: ../../example/quickstart/counter.py
:caption: counter.py
:language: python
:linenos:
Save this file as ``counter.html``:
.. literalinclude:: ../../example/quickstart/counter.html
:caption: counter.html
:language: html
:linenos:
Save this file as ``counter.css``:
.. literalinclude:: ../../example/quickstart/counter.css
:caption: counter.css
:language: css
:linenos:
Save this file as ``counter.js``:
.. literalinclude:: ../../example/quickstart/counter.js
:caption: counter.js
:language: js
:linenos:
Then open ``counter.html`` file in several browsers and play with [+] and [-].