websockets

https://websockets.readthedocs.io/en/stable
Admin
websockets is a Python library for building WebSocket servers and clients with a focus on...
Tokens:193,947
Snippets:1,441
Trust Score:8.3
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Start server with start_serving()

Source: https://websockets.readthedocs.io/en/stable/reference/legacy/server.html

Typical use of start_serving() after creating a server with serve(..., start_serving=False). Allows additional setup before the server starts accepting connections.

```python
server = await serve(..., start_serving=False)
# perform additional setup here...
# ... then start the server
await server.start_serving()
```

--------------------------------

### Start server with start_serving()

Source: https://websockets.readthedocs.io/en/stable/reference/asyncio/server.html

Shows how to delay the start of a WebSocket server until after additional setup is performed. The server is created with start_serving=False and then started explicitly with start_serving().

```python
server = await serve(..., start_serving=False)
# perform additional setup here...
# ... then start the server
await server.start_serving()

```

--------------------------------

### Define URL map and start server with route()

Source: https://websockets.readthedocs.io/en/stable/topics/routing.html

This example shows how to define a `werkzeug.routing.Map` with rules for different paths and converters, and then start a server with `route()`. The `url_map` includes rules for `/`, `/clock`, `/clock/<tzinfo:tzinfo>`, `/alarm/<datetime:alarm_at>/<tzinfo:tzinfo>`, and `/timer/<timedelta:alarm_after>`. The `main()` function starts the server on localhost port 8888.

```python
url_map = Map(
    [
        Rule(
            "/",
            redirect_to="/clock",
        ),
        Rule(
            "/clock",
            defaults={"tzinfo": datetime.timezone.utc},
            endpoint=clock,
        ),
        Rule(
            "/clock/<tzinfo:tzinfo>",
            endpoint=clock,
        ),
        Rule(
            "/alarm/<datetime:alarm_at>/<tzinfo:tzinfo>",
            endpoint=alarm,
        ),
        Rule(
            "/timer/<timedelta:alarm_after>",
            endpoint=timer,
        ),
    ],
    converters={
        "tzinfo": ZoneInfoConverter,
        "datetime": DateTimeConverter,
        "timedelta": TimeDeltaConverter,
    },
)


async def main():
    server = await route(url_map, "localhost", 8888)
    await server.serve_forever()

```

--------------------------------

### Start WebSocket server

Source: https://websockets.readthedocs.io/en/stable/intro/tutorial1.html

Starts the WebSocket server.

```bash
$ python app.py
```

--------------------------------

### Server.start_serving

Source: https://websockets.readthedocs.io/en/stable/reference/asyncio/server.html

Starts serving connections. Typically used after additional setup when the server was created with start_serving=False.

```APIDOC
## Server.start_serving()

### Description
Starts serving connections. This is useful when the server was created with start_serving=False. See asyncio.Server.start_serving().

### Method
start_serving

### Response
No return value.
```

--------------------------------

### Start WebSocket server

Source: https://websockets.readthedocs.io/en/stable/intro/tutorial1.html

Starts the WebSocket server. No output is displayed when the server starts successfully.

```bash
$ python app.py

```

--------------------------------

### Install websockets and Supervisor

Source: https://websockets.readthedocs.io/en/stable/deploy/supervisor.html

Installs the websockets library and Supervisor.

```shell
$ pip install websockets
$ pip install supervisor

```

--------------------------------

### Start Supervisor and view startup logs

Source: https://websockets.readthedocs.io/en/stable/deploy/supervisor.html

Starts Supervisor in the foreground with the given configuration and shows the expected startup logs.

```shell
$ supervisord -c supervisord.conf -n
INFO Increased RLIMIT_NOFILE limit to 1024
INFO supervisord started with pid 43596
INFO spawned: 'websockets-test_00' with pid 43597
INFO spawned: 'websockets-test_01' with pid 43598
INFO spawned: 'websockets-test_02' with pid 43599
INFO spawned: 'websockets-test_03' with pid 43600
INFO success: websockets-test_00 entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
INFO success: websockets-test_01 entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
INFO success: websockets-test_02 entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
INFO success: websockets-test_03 entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)

```

--------------------------------

### Start HTTP server with python -m http.server

Source: https://websockets.readthedocs.io/en/stable/intro/tutorial1.html

Start a local HTTP server from the directory containing the files. Then open http://localhost:8000/ to see an empty board with seven columns and six rows.

```shell
$ python -m http.server
```

--------------------------------

### Install werkzeug for route()

Source: https://websockets.readthedocs.io/en/stable/topics/routing.html

Install the third-party library `werkzeug` to use the `route()` function for complex routing.

```bash
$ pip install werkzeug

```

--------------------------------

### Start and gracefully close a WebSocket server with serve() and async with

Source: https://websockets.readthedocs.io/en/stable/reference/trio/server.html

Starts a WebSocket server with `serve()` inside a Trio nursery and uses the returned `Server` object as an asynchronous context manager to ensure graceful shutdown when the `stop` event is set.

```python
from websockets.trio.server import serve

async def handler(websocket):
    ...

# set this event to exit the server
stop = trio.Event()

with trio.open_nursery() as nursery:
    server = await nursery.start(serve, handler, port)
    async with server:
        await stop.wait()
```

--------------------------------

### Run authentication experiment

Source: https://websockets.readthedocs.io/en/stable/topics/authentication.html

Run the authentication experiment. The server starts and prints the URL to browse to.

```bash
$ python experiments/authentication/app.py
Running on http://localhost:8000/

```

--------------------------------

### Install werkzeug for websockets.sync.router

Source: https://websockets.readthedocs.io/en/stable/reference/sync/server.html

Install the required third-party library for the websockets sync router feature.

```bash
$ pip install werkzeug
```

--------------------------------

### Install websockets client in a virtualenv

Source: https://websockets.readthedocs.io/en/stable/deploy/koyeb.html

Creates a virtual environment and installs the websockets library, which provides the interactive client used to validate the deployment.

```bash
$ python -m venv websockets-client
$ . websockets-client/bin/activate
$ pip install websockets

```

--------------------------------

### WebSocketServer.start_serving

Source: https://websockets.readthedocs.io/en/stable/reference/legacy/server.html

Starts serving after the server has been created with `start_serving=False`.

```APIDOC
## [METHOD] WebSocketServer.start_serving

### Description
See `asyncio.Server.start_serving()`. Typical use:
```
server = await serve(..., start_serving=False)
# perform additional setup here...
# ... then start the server
await server.start_serving()
```

### Signature
`async start_serving()`
```

--------------------------------

### Start the websockets server

Source: https://websockets.readthedocs.io/en/stable/howto/django.html

Command to run the authentication.py script. Requires DJANGO_SETTINGS_MODULE to be set properly.

```bash
$ python authentication.py

```

--------------------------------

### Route WebSocket connections with route() and werkzeug

Source: https://websockets.readthedocs.io/en/stable/reference/trio/server.html

Example of using route() with a werkzeug.routing.Map to dispatch connections to handlers. Handlers receive URL parameters as keyword arguments. The server is started with nursery.start() and runs until the stop event is set.

```python
from websockets.trio.router import route
from werkzeug.routing import Map, Rule

async def channel_handler(websocket, channel_id):
    ...

url_map = Map([
    Rule("/channel/<uuid:channel_id>", endpoint=channel_handler),
    ...
])

# set this event to exit the server
stop = trio.Event()

with trio.open_nursery() as nursery:
    server = await nursery.start(route, url_map, ...)
    async with server:
        await stop.wait()

```

--------------------------------

### serve(handler, host=None, port=None, sock=None, ssl=None, origins=None, extensions=None, subprotocols=None, select_subprotocol=None, compression=None, process_request=None, process_response=None, server_header=None, open_timeout=None, ping_interval=None, ping_timeout=None, close_timeout=None, max_size=None, max_queue=None, logger=None, create_connection=None, **kwargs)

Source: https://websockets.readthedocs.io/en/stable/reference/sync/server.html

Creates a WebSocket server with the given handler and configuration options.

```APIDOC
## serve(handler, host=None, port=None, sock=None, ssl=None, origins=None, extensions=None, subprotocols=None, select_subprotocol=None, compression=None, process_request=None, process_response=None, server_header=None, open_timeout=None, ping_interval=None, ping_timeout=None, close_timeout=None, max_size=None, max_queue=None, logger=None, create_connection=None, **kwargs)

### Description
Creates a WebSocket server. The handler is called with a `ServerConnection` instance for each connection. Additional keyword arguments are passed to `create_server()`.

### Parameters
- **handler** (_Callable_ _[__[__ServerConnection_ _]__,__None_ _]_) - Required - Connection handler. It receives the WebSocket connection, which is a `ServerConnection`, in argument.
- **host** (_str_ _|__None_) - Optional - Network interfaces the server binds to. See `create_server()` for details.
- **port** (_int_ _|__None_) - Optional - TCP port the server listens on. See `create_server()` for details.
- **sock** (_socket_ _|__None_) - Optional - Preexisting TCP socket. `sock` replaces `host` and `port`. You may call `socket.create_server()` to create a suitable TCP socket.
- **ssl** (_SSLContext_ _|__None_) - Optional - Configuration for enabling TLS on the connection.
- **origins** (_Sequence_ _[__Origin_ _|__Pattern_ _[__str_ _]__|__None_ _]__|__None_) - Optional - Acceptable values of the `Origin` header, for defending against Cross-Site WebSocket Hijacking attacks. Values can be `str` to test for an exact match or regular expressions compiled by `re.compile()` to test against a pattern. Include `None` in the list if the lack of an origin is acceptable.
- **extensions** (_Sequence_ _[__ServerExtensionFactory_ _]__|__None_) - Optional - List of supported extensions, in order in which they should be negotiated and run.
- **subprotocols** (_Sequence_ _[__Subprotocol_ _]__|__None_) - Optional - List of supported subprotocols, in order of decreasing preference.
- **select_subprotocol** (_Callable_ _[__[__ServerConnection_ _,__Sequence_ _[__Subprotocol_ _]__]__,__Subprotocol_ _|__None_ _]__|__None_) - Optional - Callback for selecting a subprotocol among those supported by the client and the server. It receives a `ServerConnection` (not a `ServerProtocol`!) instance and a list of subprotocols offered by the client. Other than the first argument, it has the same behavior as the `ServerProtocol.select_subprotocol` method.
- **compression** (_str_ _|__None_) - Optional - The “permessage-deflate” extension is enabled by default. Set `compression` to `None` to disable it. See the compression guide for details.
- **process_request** (_Callable_ _[__[__ServerConnection_ _,__Request_ _]__,__Response_ _|__None_ _]__|__None_) - Optional - Intercept the request during the opening handshake. Return an HTTP response to force the response. Return `None` to continue normally. When you force an HTTP 101 Continue response, the handshake is successful. Else, the connection is aborted.
- **process_response** (_Callable_ _[__[__ServerConnection_ _,__Request_ _,__Response_ _]__,__Response_ _|__None_ _]__|__None_) - Optional - Intercept the response during the opening handshake. Modify the response or return a new HTTP response to force the response. Return `None` to continue normally. When you force an HTTP 101 Continue response, the handshake is successful. Else, the connection is aborted.
- **server_header** (_str_ _|__None_) - Optional - Value of the `Server` response header. It defaults to `"Python/x.y.z websockets/X.Y"`. Setting it to `None` removes the header.
- **open_timeout** (_float_ _|__None_) - Optional - Timeout for opening connections in seconds. `None` disables the timeout.
- **ping_interval** (_float_ _|__None_) - Optional - Interval between keepalive pings in seconds. `None` disables keepalive.
- **ping_timeout** (_float_ _|__None_) - Optional - Timeout for keepalive pings in seconds. `None` disables timeouts.
- **close_timeout** (_float_ _|__None_) - Optional - Timeout for closing connections in seconds. `None` disables the timeout.
- **max_size** (_int_ _|__None_ _|__tuple_ _[__int_ _|__None_ _,__int_ _|__None_ _]_) - Optional - Maximum size of incoming messages in bytes. `None` disables the limit. You may pass a `(max_message_size, max_fragment_size)` tuple to set different limits for messages and fragments when you expect long messages sent in short fragments.
- **max_queue** (_int_ _|__None_ _|__tuple_ _[__int_ _|__None_ _,__int_ _|__None_ _]_) - Optional - High-water mark of the buffer where frames are received. It defaults to 16 frames. The low-water mark defaults to `max_queue // 4`. You may pass a `(high, low)` tuple to set the high-water and low-water marks. If you want to disable flow control entirely, you may set it to `None`, although that’s a bad idea.
- **logger** (_Logger_ _|__LoggerAdapter_ _[__Any_ _]__|__None_) - Optional - Logger for this server. It defaults to `logging.getLogger("websockets.server")`. See the logging guide for details.
- **create_connection** (_type_ _[__ServerConnection_ _]__|__None_) - Optional - Factory for the `ServerConnection` managing the connection. Set it to a wrapper or a subclass to customize connection handling.
- **kwargs** - Optional - Any other keyword arguments are passed to `create_server()`.
```

--------------------------------

### Install websockets with pip

Source: https://websockets.readthedocs.io/en/stable/intro/index.html

Install the websockets library using pip. Requires Python ≥ 3.11 and has no dependencies.

```shell
$ pip install websockets

```

--------------------------------

### Define start and handler coroutines in app.py

Source: https://websockets.readthedocs.io/en/stable/intro/tutorial2.html

In app.py, define a new handler coroutine that receives and parses the "init" event, then calls start(). The start() coroutine initializes a Connect4 game, stores it in the JOIN dictionary with a secret token, sends the token to the first player, and prints test messages. The handler asserts the event type is "init" before starting the game.

```python
import secrets


JOIN = {}


async def start(websocket):
    # Initialize a Connect Four game, the set of WebSocket connections
    # receiving moves from this game, and secret access token.
    game = Connect4()
    connected = {websocket}

    join_key = secrets.token_urlsafe(12)
    JOIN[join_key] = game, connected

    try:
        # Send the secret access token to the browser of the first player,
        # where it'll be used for building a "join" link.
        event = {
            "type": "init",
            "join": join_key,
        }
        await websocket.send(json.dumps(event))

        # Temporary - for testing.
        print("first player started game", id(game))
        async for message in websocket:
            print("first player sent", message)

    finally:
        del JOIN[join_key]


async def handler(websocket):
    # Receive and parse the "init" event from the UI.
    message = await websocket.recv()
    event = json.loads(message)
    assert event["type"] == "init"

    # First player starts a new game.
    await start(websocket)

```

--------------------------------

### Connect a browser to a WebSocket server (show_time.py, show_time.html, show_time.js)

Source: https://websockets.readthedocs.io/en/stable/intro/examples.html

This example shows how to connect a browser to a WebSocket server. It includes a Python server that sends the current time, an HTML file that loads the JavaScript, and a JavaScript file that creates a WebSocket connection and displays messages.

```python
#!/usr/bin/env python

import asyncio
import datetime
import random

from websockets.asyncio.server import serve

async def show_time(websocket):
    while True:
        message = datetime.datetime.now(tz=datetime.timezone.utc).isoformat()
        await websocket.send(message)
        await asyncio.sleep(random.random() * 2 + 1)

async def main():
    server = await serve(show_time, "localhost", 5678)
    await server.serve_forever()

if __name__ == "__main__":
    asyncio.run(main())

```

```html
<!DOCTYPE html>
<html lang="en">
    <head>
        <title>WebSocket demo</title>
    </head>
    <body>
        <script src="show_time.js"></script>
    </body>
</html>

```

```javascript
window.addEventListener("DOMContentLoaded", () => {
  const messages = document.createElement("ul");
  document.body.appendChild(messages);

  const websocket = new WebSocket("ws://localhost:5678/");
  websocket.onmessage = ({ data }) => {
    const message = document.createElement("li");
    const content = document.createTextNode(data);
    message.appendChild(content);
    messages.appendChild(message);
  };
});

```

--------------------------------

### Client using the asyncio API

Source: https://websockets.readthedocs.io/en/stable?__cf_chl_rt_tk=XGuRnwcsNG2zjc7na0OzPDPeP2MQ53E.vI5Zb2Fn3W4-1790900960-1.0.1.1-9WN7.u6S3u.ZZ6cv6PZwB5fvN.8_hVGcGWJN8neCxVQ

Client example using the asyncio implementation. It connects to ws://localhost:8765, sends a 'Hello world!' message, and prints the received response.

```python
#!/usr/bin/env python

"""Client using the asyncio API."""

import asyncio
from websockets.asyncio.client import connect


async def hello():
    async with connect("ws://localhost:8765") as websocket:
        await websocket.send("Hello world!")
        message = await websocket.recv()
        print(message)


if __name__ == "__main__":
    asyncio.run(hello())

```

--------------------------------

### Call play for PLAYER1 in start()

Source: https://websockets.readthedocs.io/en/stable/intro/tutorial2.html

Replaces the temporary testing code in the start() function to invoke the play coroutine for the first player.

```python
await play(websocket, game, PLAYER1, connected)

```

--------------------------------

### Install python-socks for SOCKS proxy support

Source: https://websockets.readthedocs.io/en/stable/topics/proxies.html

Required to connect through a SOCKS proxy. Install the third-party library python-socks with the asyncio extra.

```bash
$ pip install python-socks\[asyncio\]

```

--------------------------------

### Connect Four WebSocket solution (app.py, index.html, main.js)

Source: https://websockets.readthedocs.io/en/stable/intro/tutorial1.html

Complete solution for the Connect Four WebSocket tutorial: a Python asyncio server (app.py) that handles play events and sends play/win/error events, an HTML page (index.html) that loads the board and main.js, and a JavaScript client (main.js) that renders the board, sends moves, and processes incoming events. The server listens on port 8001 and the client connects to ws://localhost:8001/.

```python
#!/usr/bin/env python

import asyncio
import itertools
import json

from websockets.asyncio.server import serve

from connect4 import PLAYER1, PLAYER2, Connect4


async def handler(websocket):
    # Initialize a Connect Four game.
    game = Connect4()

    # Players take alternate turns, using the same browser.
    turns = itertools.cycle([PLAYER1, PLAYER2])
    player = next(turns)

    async for message in websocket:
        # Parse a "play" event from the UI.
        event = json.loads(message)
        assert event["type"] == "play"
        column = event["column"]

        try:
            # Play the move.
            row = game.play(player, column)
        except ValueError as exc:
            # Send an "error" event if the move was illegal.
            event = {
                "type": "error",
                "message": str(exc),
            }
            await websocket.send(json.dumps(event))
            continue

        # Send a "play" event to update the UI.
        event = {
            "type": "play",
            "player": player,
            "column": column,
            "row": row,
        }
        await websocket.send(json.dumps(event))

        # If move is winning, send a "win" event.
        if game.winner is not None:
            event = {
                "type": "win",
                "player": game.winner,
            }
            await websocket.send(json.dumps(event))

        # Alternate turns.
        player = next(turns)


async def main():
    server = await serve(handler, "", 8001)
    await server.serve_forever()


if __name__ == "__main__":
    asyncio.run(main())

```

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Connect Four</title>
  </head>
  <body>
    <div class="board"></div>
    <script src="main.js" type="module"></script>
  </body>
</html>

```

```javascript
import { createBoard, playMove } from "./connect4.js";

function showMessage(message) {
  window.setTimeout(() => window.alert(message), 50);
}

function receiveMoves(board, websocket) {
  websocket.addEventListener("message", ({ data }) => {
    const event = JSON.parse(data);
    switch (event.type) {
      case "play":
        // Update the UI with the move.
        playMove(board, event.player, event.column, event.row);
        break;
      case "win":
        showMessage(`Player ${event.player} wins!`);
        // No further messages are expected; close the WebSocket connection.
        websocket.close(1000);
        break;
      case "error":
        showMessage(event.message);
        break;
      default:
        throw new Error(`Unsupported event type: ${event.type}.`);
    }
  });
}

function sendMoves(board, websocket) {
  // When clicking a column, send a "play" event for a move in that column.
  board.addEventListener("click", ({ target }) => {
    const column = target.dataset.column;
    // Ignore clicks outside a column.
    if (column === undefined) {
      return;
    }
    const event = {
      type: "play",
      column: parseInt(column, 10),
    };
    websocket.send(JSON.stringify(event));
  });
}

window.addEventListener("DOMContentLoaded", () => {
  // Initialize the UI.
  const board = document.querySelector(".board");
  createBoard(board);
  // Open the WebSocket connection and register event handlers.
  const websocket = new WebSocket("ws://localhost:8001/");
  receiveMoves(board, websocket);
  sendMoves(board, websocket);
});

```

--------------------------------

### Add all files and commit initial implementation

Source: https://websockets.readthedocs.io/en/stable/intro/tutorial3.html

Stages all files and creates a commit for the initial implementation of the Connect Four game.

```bash
$ git add .
$ git commit -m "Initial implementation of Connect Four game."
[main 7f0b2c4] Initial implementation of Connect Four game.
 6 files changed, 500 insertions(+)
 create mode 100644 app.py
 create mode 100644 connect4.css
 create mode 100644 connect4.js
 create mode 100644 connect4.py
 create mode 100644 index.html
 create mode 100644 main.js

```

--------------------------------

### Install watchdog with watchmedo

Source: https://websockets.readthedocs.io/en/stable/howto/autoreload.html

Install the watchdog package which provides the watchmedo shell utility. Use pip with the 'watchdog[watchmedo]' extra.

```shell
$ pip install 'watchdog[watchmedo]'

```

--------------------------------

### Client using the trio API

Source: https://websockets.readthedocs.io/en/stable?__cf_chl_rt_tk=XGuRnwcsNG2zjc7na0OzPDPeP2MQ53E.vI5Zb2Fn3W4-1790900960-1.0.1.1-9WN7.u6S3u.ZZ6cv6PZwB5fvN.8_hVGcGWJN8neCxVQ

Client example using the trio implementation. It connects to ws://localhost:8765, sends a 'Hello world!' message, and prints the received response.

```python
#!/usr/bin/env python

"""Client using the trio API."""

import trio
from websockets.trio.client import connect


async def hello():
    async with connect("ws://localhost:8765") as websocket:
        await websocket.send("Hello world!")
        message = await websocket.recv()
        print(message)


if __name__ == "__main__":
    trio.run(hello)

```

--------------------------------

### Init event to start a game

Source: https://websockets.readthedocs.io/en/stable/intro/tutorial2.html

Event sent by the first player to start a game. It contains only the type field set to "init".

```json
{type: "init"}

```

--------------------------------

### Example: route() with werkzeug.routing.Map

Source: https://websockets.readthedocs.io/en/stable/reference/asyncio/server.html

Creates a WebSocket server that dispatches connections to handlers based on URL patterns. Handlers receive captured URL parameters as keyword arguments. The server runs until the stop event is set.

```python
from websockets.asyncio.router import route
from werkzeug.routing import Map, Rule

async def channel_handler(websocket, channel_id):
    ...

url_map = Map([
    Rule("/channel/<uuid:channel_id>", endpoint=channel_handler),
    ...
])

# set this event to exit the server
stop = asyncio.Event()

async with route(url_map, ...) as server:
    await stop.wait()

```

--------------------------------

### Counter example CSS styles

Source: https://websockets.readthedocs.io/en/stable/intro/examples.html

Styles for the counter example. Defines layout, button colors (red for minus, green for plus), and font. Save this file as counter.css.

```css
body {
    font-family: "Courier New", sans-serif;
    text-align: center;
}
.buttons {
    font-size: 4em;
    display: flex;
    justify-content: center;
}
.button, .value {
    line-height: 1;
    padding: 2rem;
    margin: 2rem;
    border: medium solid;
    min-height: 1em;
    min-width: 1em;
}
.button {
    cursor: pointer;
    user-select: none;
}
.minus {
    color: red;
}
.plus {
    color: green;
}
.value {
    min-width: 2em;
}
.state {
    font-size: 2em;
}

```

--------------------------------

### Start and stop a WebSocket server with serve()

Source: https://websockets.readthedocs.io/en/stable/reference/legacy/server.html

Manually shut down a WebSocket server started with websockets.legacy.server.serve(). The future 'stop' is awaited to keep the server running until it is set, then close() and wait_closed() are called to shut down gracefully.

```python
# set this future to exit the server
stop = asyncio.get_running_loop().create_future()

server = await serve(...)
await stop
server.close()
await server.wait_closed()

```

--------------------------------

### serve(handler, host=None, port=None, ...)

Source: https://websockets.readthedocs.io/en/stable/reference/asyncio/server.html

Documentation for the `serve()` function used to create a WebSocket server in the websockets library.

```APIDOC
## serve(handler, host=None, port=None, *, origins=None, extensions=None, subprotocols=None, select_subprotocol=None, compression='deflate', process_request=None, process_response=None, server_header='Python/x.y.z websockets/X.Y', open_timeout=10, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2**20, max_queue=16, write_limit=2**15, logger=None, create_connection=None)

### Description
Creates a WebSocket server. The handler is a coroutine that receives a `ServerConnection` instance and is awaited for each connection. The server binds to the specified host and port.

### Parameters
- **handler** (_Callable_ _[__[__ServerConnection_ _]__,__Awaitable_ _[__None_ _]__]_) – Connection handler. It receives the WebSocket connection, which is a `ServerConnection`, in argument.
- **host** (_str_ _|__None_) – Network interfaces the server binds to. See `create_server()` for details.
- **port** (_int_ _|__None_) – TCP port the server listens on. See `create_server()` for details.
- **origins** (_Sequence_ _[__Origin_ _|__Pattern_ _[__str_ _]__|__None_ _]__|__None_) – Acceptable values of the `Origin` header, for defending against Cross-Site WebSocket Hijacking attacks. Values can be `str` to test for an exact match or regular expressions compiled by `re.compile()` to test against a pattern. Include `None` in the list if the lack of an origin is acceptable.
- **extensions** (_Sequence_ _[__ServerExtensionFactory_ _]__|__None_) – List of supported extensions, in order in which they should be negotiated and run.
- **subprotocols** (_Sequence_ _[__Subprotocol_ _]__|__None_) – List of supported subprotocols, in order of decreasing preference.
- **select_subprotocol** (_Callable_ _[__[__ServerConnection_ _,__Sequence_ _[__Subprotocol_ _]__]__,__Subprotocol_ _|__None_ _]__|__None_) – Callback for selecting a subprotocol among those supported by the client and the server. It receives a `ServerConnection` (not a `ServerProtocol`!) instance and a list of subprotocols offered by the client. Other than the first argument, it has the same behavior as the `ServerProtocol.select_subprotocol` method.
- **compression** (_str_ _|__None_) – The “permessage-deflate” extension is enabled by default. Set `compression` to `None` to disable it. See the compression guide for details.
- **process_request** (_Callable_ _[__[__ServerConnection_ _,__Request_ _]__,__Awaitable_ _[__Response_ _|__None_ _]__|__Response_ _|__None_ _]__|__None_) – Intercept the request during the opening handshake. Return an HTTP response to force the response or `None` to continue normally. When you force an HTTP 101 Continue response, the handshake is successful. Else, the connection is aborted. `process_request` may be a function or a coroutine.
- **process_response** (_Callable_ _[__[__ServerConnection_ _,__Request_ _,__Response_ _]__,__Awaitable_ _[__Response_ _|__None_ _]__|__Response_ _|__None_ _]__|__None_) – Intercept the response during the opening handshake. Return an HTTP response to force the response or `None` to continue normally. When you force an HTTP 101 Continue response, the handshake is successful. Else, the connection is aborted. `process_response` may be a function or a coroutine.
- **server_header** (_str_ _|__None_) – Value of the `Server` response header. It defaults to `"Python/x.y.z websockets/X.Y"`. Setting it to `None` removes the header.
- **open_timeout** (_float_ _|__None_) – Timeout for opening connections in seconds. `None` disables the timeout.
- **ping_interval** (_float_ _|__None_) – Interval between keepalive pings in seconds. `None` disables keepalive.
- **ping_timeout** (_float_ _|__None_) – Timeout for keepalive pings in seconds. `None` disables timeouts.
- **close_timeout** (_float_ _|__None_) – Timeout for closing connections in seconds. `None` disables the timeout.
- **max_size** (_int_ _|__None_ _|__tuple_ _[__int_ _|__None_ _,__int_ _|__None_ _]_) – Maximum size of incoming messages in bytes. `None` disables the limit. You may pass a `(max_message_size, max_fragment_size)` tuple to set different limits for messages and fragments when you expect long messages sent in short fragments.
- **max_queue** (_int_ _|__None_ _|__tuple_ _[__int_ _|__None_ _,__int_ _|__None_ _]_) – High-water mark of the buffer where frames are received. It defaults to 16 frames. The low-water mark defaults to `max_queue // 4`. You may pass a `(high, low)` tuple to set the high-water and low-water marks. If you want to disable flow control entirely, you may set it to `None`, although that’s a bad idea.
- **write_limit** (_int_ _|__tuple_ _[__int_ _,__int_ _|__None_ _]_) – High-water mark of write buffer in bytes. It is passed to `set_write_buffer_limits()`. It defaults to 32 KiB. You may pass a `(high, low)` tuple to set the high-water and low-water marks.
- **logger** (_Logger_ _|__LoggerAdapter_ _[__Any_ _]__|__None_) – Logger for this server. It defaults to `logging.getLogger("websockets.server")`. See the logging guide for details.
- **create_connection** (_type_ _[__ServerConnection_ _]__|__None_) – Factory for the `ServerConnection` managing the connection. Set it to a wrapper or a subclass to customize connection handling.
```

--------------------------------

### Counter example HTML page

Source: https://websockets.readthedocs.io/en/stable/intro/examples.html

HTML page for the counter example. Displays minus and plus buttons, the current value, and the number of online users. Links to counter.css and counter.js. Save this file as counter.html.

```html
<!DOCTYPE html>
<html lang="en">
    <head>
        <title>WebSocket demo</title>
        <link href="counter.css" rel="stylesheet">
    </head>
    <body>
        <div class="buttons">
            <div class="minus button">-</div>
            <div class="value">?</div>
            <div class="plus button">+</div>
        </div>
        <div class="state">
            <span class="users">?</span> online
        </div>
        <script src="counter.js"></script>
    </body>
</html>

```

--------------------------------

### subprotocol

Source: https://websockets.readthedocs.io/en/stable/reference/legacy/server.html

Attribute to get the negotiated subprotocol, if any.

```APIDOC
## Attribute: subprotocol

### Description
Subprotocol, if one was negotiated. Available after the opening handshake, once the WebSocket connection is open.

### Type
`Subprotocol | None`

### Access
Read-only attribute

### Availability
After the opening handshake.

### Example
```python
subprotocol = websocket.subprotocol
```
```

--------------------------------

### Client using asyncio, threading, and trio APIs

Source: https://websockets.readthedocs.io/en/stable/index.html

Client implementations for the asyncio, threading, and trio APIs. Each client connects to ws://localhost:8765, sends "Hello world!", receives the echoed message, and prints it. The asyncio and trio versions use async/await, while the threading version uses synchronous code.

```python
#!/usr/bin/env python

"""Client using the asyncio API."""

import asyncio
from websockets.asyncio.client import connect


async def hello():
    async with connect("ws://localhost:8765") as websocket:
        await websocket.send("Hello world!")
        message = await websocket.recv()
        print(message)


if __name__ == "__main__":
    asyncio.run(hello())

```

```python
#!/usr/bin/env python

"""Client using the threading API."""

from websockets.sync.client import connect


def hello():
    with connect("ws://localhost:8765") as websocket:
        websocket.send("Hello world!")
        message = websocket.recv()
        print(message)


if __name__ == "__main__":
    hello()

```

```python
#!/usr/bin/env python

"""Client using the trio API."""

import trio
from websockets.trio.client import connect


async def hello():
    async with connect("ws://localhost:8765") as websocket:
        await websocket.send("Hello world!")
        message = await websocket.recv()
        print(message)


if __name__ == "__main__":
    trio.run(hello)

```

--------------------------------

### Connect with interactive client

Source: https://websockets.readthedocs.io/en/stable/intro/tutorial1.html

Launches the interactive client to test the WebSocket server. Type a message and press Enter to send it. Exit with Ctrl-C or Ctrl-D.

```bash
$ websockets ws://localhost:8001/

```

--------------------------------

### Counter example WebSocket client

Source: https://websockets.readthedocs.io/en/stable/intro/examples.html

Client-side JavaScript for the counter example. Connects to the WebSocket server at ws://localhost:6789/, sends minus/plus actions on button clicks, and updates the displayed value and user count based on incoming messages. Save this file as counter.js.

```javascript
window.addEventListener("DOMContentLoaded", () => {
  const websocket = new WebSocket("ws://localhost:6789/");

  document.querySelector(".minus").addEventListener("click", () => {
    websocket.send(JSON.stringify({ action: "minus" }));
  });

  document.querySelector(".plus").addEventListener("click", () => {
    websocket.send(JSON.stringify({ action: "plus" }));
  });

  websocket.onmessage = ({ data }) => {
    const event = JSON.parse(data);
    switch (event.type) {
      case "value":
        document.querySelector(".value").textContent = event.value;
        break;
      case "users":
        const users = `${event.count} user${event.count == 1 ? "" : "s"}`;
        document.querySelector(".users").textContent = users;
        break;
      default:
        console.error("unsupported event", event);
    }
  };
});

```

--------------------------------

### Initialize git repository

Source: https://websockets.readthedocs.io/en/stable/deploy/koyeb.html

Commands to create a new directory, initialize a git repository with the main branch, and create an initial empty commit. The output shows the repository initialization and commit confirmation.

```bash
$ mkdir websockets-echo
$ cd websockets-echo
$ git init -b main
Initialized empty Git repository in websockets-echo/.git/
$ git commit --allow-empty -m "Initial commit."
[main (root-commit) 740f699] Initial commit.

```

--------------------------------

### response_headers

Source: https://websockets.readthedocs.io/en/stable/reference/legacy/server.html

Attribute to get the opening handshake response headers.

```APIDOC
## Attribute: response_headers

### Description
Opening handshake response headers. Available after the opening handshake, once the WebSocket connection is open.

### Type
`Headers`

### Access
Read-only attribute

### Availability
After the opening handshake.

### Example
```python
headers = websocket.response_headers
```
```
Tokens:
Raw