Skip to content

Latest commit

 

History

History
164 lines (112 loc) · 4.59 KB

quickstart.rst

File metadata and controls

164 lines (112 loc) · 4.59 KB

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.

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.

TLS vs. SSL

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.

See the documentation of the :mod:`ssl` module for details on configuring the TLS context securely.

.. 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`.

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 [-].