API

Design

websockets provides complete client and server implementations, as shown in the getting started guide. These functions are built on top of low-level APIs reflecting the two phases of the WebSocket protocol:

  1. An opening handshake, in the form of an HTTP Upgrade request;
  2. Data transfer, as framed messages, ending with a closing handshake.

The first phase is designed to integrate with existing HTTP software. websockets provides functions to build and validate the request and response headers.

The second phase is the core of the WebSocket protocol. websockets provides a standalone implementation on top of asyncio with a very simple API.

For convenience, public APIs can be imported directly from the websockets package, unless noted otherwise. Anything that isn’t listed in this document is a private API.

High-level

Server

The websockets.server module defines a simple WebSocket server API.

websockets.server.serve(ws_handler, host=None, port=None, *, create_protocol=None, timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None, origins=None, subprotocols=None, extra_headers=None, **kwds)

Create, start, and return a WebSocketServer object.

serve() is a wrapper around the event loop’s create_server() method. Internally, the function creates and starts a Server object by calling create_server(). The WebSocketServer keeps a reference to this object.

The returned WebSocketServer and its resources can be cleaned up by calling its close() and wait_closed() methods.

On Python 3.5 and greater, serve() can also be used as an asynchronous context manager. In this case, the server is shut down when exiting the context.

The ws_handler argument is the WebSocket handler. It must be a coroutine accepting two arguments: a WebSocketServerProtocol and the request URI.

The host and port arguments, as well as unrecognized keyword arguments, are passed along to create_server(). For example, you can set the ssl keyword argument to a SSLContext to enable TLS.

The create_protocol parameter allows customizing the asyncio protocol that manages the connection. It should be a callable or class accepting the same arguments as WebSocketServerProtocol and returning a WebSocketServerProtocol instance. It defaults to WebSocketServerProtocol.

The behavior of the timeout, max_size, and max_queue, read_limit, and write_limit optional arguments is described in the documentation of WebSocketCommonProtocol.

serve() also accepts the following optional arguments:

  • origins defines acceptable Origin HTTP headers — include '' if the lack of an origin is acceptable
  • subprotocols is a list of supported subprotocols in order of decreasing preference
  • extra_headers sets additional HTTP response headers — it can be a mapping, an iterable of (name, value) pairs, or a callable taking the request path and headers in arguments.

Whenever a client connects, the server accepts the connection, creates a WebSocketServerProtocol, performs the opening handshake, and delegates to the WebSocket handler. Once the handler completes, the server performs the closing handshake and closes the connection.

Since there’s no useful way to propagate exceptions triggered in handlers, they’re sent to the 'websockets.server' logger instead. Debugging is much easier if you configure logging to print them:

import logging
logger = logging.getLogger('websockets.server')
logger.setLevel(logging.ERROR)
logger.addHandler(logging.StreamHandler())
class websockets.server.WebSocketServer(loop)[source]

Wraps an underlying Server object.

This class provides the return type of serve(). This class shouldn’t be instantiated directly.

Objects of this class store a reference to an underlying Server object returned by create_server(). The class stores a reference rather than inheriting from Server in part because create_server() doesn’t support passing a custom Server class.

WebSocketServer supports cleaning up the underlying Server object and other resources by implementing the interface of asyncio.events.AbstractServer, namely its close() and wait_closed() methods.

close()[source]

Close the underlying server, and clean up connections.

This calls close() on the underlying Server object, closes open connections with status code 1001, and stops accepting new connections.

wait_closed()[source]

Wait until the underlying server and all connections are closed.

This calls wait_closed() on the underlying Server object and waits until closing handshakes are complete and all connections are closed.

This method must be called after close().

class websockets.server.WebSocketServerProtocol(ws_handler, ws_server, *, host=None, port=None, secure=None, timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None, origins=None, subprotocols=None, extra_headers=None)[source]

Complete WebSocket server implementation as an asyncio.Protocol.

This class inherits most of its methods from WebSocketCommonProtocol.

For the sake of simplicity, it doesn’t rely on a full HTTP implementation. Its support for HTTP responses is very limited.

handshake(origins=None, subprotocols=None, extra_headers=None)[source]

Perform the server side of the opening handshake.

If provided, origins is a list of acceptable HTTP Origin values. Include '' if the lack of an origin is acceptable.

If provided, subprotocols is a list of supported subprotocols in order of decreasing preference.

If provided, extra_headers sets additional HTTP response headers. It can be a mapping or an iterable of (name, value) pairs. It can also be a callable taking the request path and headers in arguments.

Raise InvalidHandshake or a subclass if the handshake fails.

Return the URI of the request.

process_request(path, request_headers)[source]

Intercept the HTTP request and return an HTTP response if needed.

request_headers are a HTTPMessage.

If this coroutine returns None, the WebSocket handshake continues. If it returns a status code, headers and a optionally a response body, that HTTP response is sent and the connection is closed.

The HTTP status must be a HTTPStatus. HTTP headers must be an iterable of (name, value) pairs. If provided, the HTTP response body must be bytes.

(HTTPStatus was added in Python 3.5. Use a compatible object on earlier versions. Look at SWITCHING_PROTOCOLS in websockets.compatibility for an example.)

This method may be overridden to check the request headers and set a different status, for example to authenticate the request and return HTTPStatus.UNAUTHORIZED or HTTPStatus.FORBIDDEN.

It is declared as a coroutine because such authentication checks are likely to require network requests.

static select_subprotocol(client_protos, server_protos)[source]

Pick a subprotocol among those offered by the client.

Client

The websockets.client module defines a simple WebSocket client API.

websockets.client.connect(uri, *, create_protocol=None, timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None, origin=None, subprotocols=None, extra_headers=None, **kwds)

This coroutine connects to a WebSocket server at a given uri.

It yields a WebSocketClientProtocol which can then be used to send and receive messages.

connect() is a wrapper around the event loop’s create_connection() method. Unknown keyword arguments are passed to create_connection().

For example, you can set the ssl keyword argument to a SSLContext to enforce some TLS settings. When connecting to a wss:// URI, if this argument isn’t provided explicitly, it’s set to True, which means Python’s default SSLContext is used.

The behavior of the timeout, max_size, and max_queue, read_limit, and write_limit optional arguments is described in the documentation of WebSocketCommonProtocol.

The create_protocol parameter allows customizing the asyncio protocol that manages the connection. It should be a callable or class accepting the same arguments as WebSocketClientProtocol and returning a WebSocketClientProtocol instance. It defaults to WebSocketClientProtocol.

connect() also accepts the following optional arguments:

  • origin sets the Origin HTTP header
  • subprotocols is a list of supported subprotocols in order of decreasing preference
  • extra_headers sets additional HTTP request headers – it can be a mapping or an iterable of (name, value) pairs

connect() raises InvalidURI if uri is invalid and InvalidHandshake if the opening handshake fails.

On Python 3.5, connect() can be used as a asynchronous context manager. In that case, the connection is closed when exiting the context.

class websockets.client.WebSocketClientProtocol(*, host=None, port=None, secure=None, timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None)[source]

Complete WebSocket client implementation as an asyncio.Protocol.

This class inherits most of its methods from WebSocketCommonProtocol.

handshake(wsuri, origin=None, subprotocols=None, extra_headers=None)[source]

Perform the client side of the opening handshake.

If provided, origin sets the Origin HTTP header.

If provided, subprotocols is a list of supported subprotocols in order of decreasing preference.

If provided, extra_headers sets additional HTTP request headers. It must be a mapping or an iterable of (name, value) pairs.

Shared

The websockets.protocol module handles WebSocket control and data frames as specified in sections 4 to 8 of RFC 6455.

class websockets.protocol.WebSocketCommonProtocol(*, host=None, port=None, secure=None, timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None)[source]

This class implements common parts of the WebSocket protocol.

It assumes that the WebSocket connection is established. The handshake is managed in subclasses such as WebSocketServerProtocol and WebSocketClientProtocol.

It runs a task that stores incoming data frames in a queue and deals with control frames automatically. It sends outgoing data frames and performs the closing handshake.

The host, port and secure parameters are simply stored as attributes for handlers that need them.

The timeout parameter defines the maximum wait time in seconds for completing the closing handshake and, only on the client side, for terminating the TCP connection. close() will complete in at most this time on the server side and twice this time on the client side.

The max_size parameter enforces the maximum size for incoming messages in bytes. The default value is 1MB. None disables the limit. If a message larger than the maximum size is received, recv() will raise ConnectionClosed and the connection will be closed with status code 1009.

The max_queue parameter sets the maximum length of the queue that holds incoming messages. The default value is 32. 0 disables the limit. Messages are added to an in-memory queue when they’re received; then recv() pops from that queue. In order to prevent excessive memory consumption when messages are received faster than they can be processed, the queue must be bounded. If the queue fills up, the protocol stops processing incoming data until recv() is called. In this situation, various receive buffers (at least in asyncio and in the OS) will fill up, then the TCP receive window will shrink, slowing down transmission to avoid packet loss.

Since Python can use up to 4 bytes of memory to represent a single character, each websocket connection may use up to 4 * max_size * max_queue bytes of memory to store incoming messages. By default, this is 128MB. You may want to lower the limits, depending on your application’s requirements.

The read_limit argument sets the high-water limit of the buffer for incoming bytes. The low-water limit is half the high-water limit. The default value is 64kB, half of asyncio’s default (based on the current implementation of StreamReader).

The write_limit argument sets the high-water limit of the buffer for outgoing bytes. The low-water limit is a quarter of the high-water limit. The default value is 64kB, equal to asyncio’s default (based on the current implementation of _FlowControlMixin).

As soon as the HTTP request and response in the opening handshake are processed, the request path is available in the path attribute, and the request and response HTTP headers are available:

  • as a HTTPMessage in the request_headers and response_headers attributes
  • as an iterable of (name, value) pairs in the raw_request_headers and raw_response_headers attributes

These attributes must be treated as immutable.

If a subprotocol was negotiated, it’s available in the subprotocol attribute.

Once the connection is closed, the status code is available in the close_code attribute and the reason in close_reason.

close(code=1000, reason='')[source]

This coroutine performs the closing handshake.

It waits for the other end to complete the handshake. It doesn’t do anything once the connection is closed. Thus it’s idemptotent.

It’s safe to wrap this coroutine in ensure_future() since errors during connection termination aren’t particularly useful.

code must be an int and reason a str.

recv()[source]

This coroutine receives the next message.

It returns a str for a text frame and bytes for a binary frame.

When the end of the message stream is reached, recv() raises ConnectionClosed. This can happen after a normal connection closure, a protocol error or a network failure.

Changed in version 3.0: recv() used to return None instead. Refer to the changelog for details.

send(data)[source]

This coroutine sends a message.

It sends str as a text frame and bytes as a binary frame. It raises a TypeError for other inputs.

ping(data=None)[source]

This coroutine sends a ping.

It returns a Future which will be completed when the corresponding pong is received and which you may ignore if you don’t want to wait.

A ping may serve as a keepalive or as a check that the remote endpoint received all messages up to this point, with yield from ws.ping().

By default, the ping contains four random bytes. The content may be overridden with the optional data argument which must be of type str (which will be encoded to UTF-8) or bytes.

pong(data=b'')[source]

This coroutine sends a pong.

An unsolicited pong may serve as a unidirectional heartbeat.

The content may be overridden with the optional data argument which must be of type str (which will be encoded to UTF-8) or bytes.

local_address

Local address of the connection.

This is a (host, port) tuple or None if the connection hasn’t been established yet.

remote_address

Remote address of the connection.

This is a (host, port) tuple or None if the connection hasn’t been established yet.

open

This property is True when the connection is usable.

It may be used to detect disconnections but this is discouraged per the EAFP principle. When open is False, using the connection raises a ConnectionClosed exception.

state_name

Current connection state, as a string.

Possible states are defined in the WebSocket specification: CONNECTING, OPEN, CLOSING, or CLOSED.

To check if the connection is open, use open instead.

Exceptions

exception websockets.exceptions.AbortHandshake(status, headers, body=None)[source]

Exception raised to abort a handshake and return a HTTP response.

exception websockets.exceptions.InvalidHandshake[source]

Exception raised when a handshake request or response is invalid.

exception websockets.exceptions.InvalidMessage[source]

Exception raised when the HTTP message in a handshake request is malformed.

exception websockets.exceptions.InvalidOrigin[source]

Exception raised when the origin in a handshake request is forbidden.

exception websockets.exceptions.InvalidState[source]

Exception raised when an operation is forbidden in the current state.

exception websockets.exceptions.InvalidStatusCode(status_code)[source]

Exception raised when a handshake response status code is invalid.

Provides the integer status code in its status_code attribute.

exception websockets.exceptions.InvalidURI[source]

Exception raised when an URI isn’t a valid websocket URI.

exception websockets.exceptions.ConnectionClosed(code, reason)[source]

Exception raised when trying to read or write on a closed connection.

Provides the connection close code and reason in its code and reason attributes respectively.

exception websockets.exceptions.PayloadTooBig[source]

Exception raised when a frame’s payload exceeds the maximum size.

exception websockets.exceptions.WebSocketProtocolError[source]

Internal exception raised when the remote side breaks the protocol.

Low-level

Opening handshake

The websockets.handshake module deals with the WebSocket opening handshake according to section 4 of RFC 6455.

It provides functions to implement the handshake with any existing HTTP library. You must pass to these functions:

  • A set_header function accepting a header name and a header value,
  • A get_header function accepting a header name and returning the header value.

The inputs and outputs of get_header and set_header are str objects containing only ASCII characters.

Some checks cannot be performed because they depend too much on the context; instead, they’re documented below.

To accept a connection, a server must:

  • Read the request, check that the method is GET, and check the headers with check_request(),
  • Send a 101 response to the client with the headers created by build_response() if the request is valid; otherwise, send an appropriate HTTP error code.

To open a connection, a client must:

  • Send a GET request to the server with the headers created by build_request(),
  • Read the response, check that the status code is 101, and check the headers with check_response().
websockets.handshake.build_request(set_header)[source]

Build a handshake request to send to the server.

Return the key which must be passed to check_response().

websockets.handshake.check_request(get_header)[source]

Check a handshake request received from the client.

If the handshake is valid, this function returns the key which must be passed to build_response().

Otherwise it raises an InvalidHandshake exception and the server must return an error like 400 Bad Request.

This function doesn’t verify that the request is an HTTP/1.1 or higher GET request and doesn’t perform Host and Origin checks. These controls are usually performed earlier in the HTTP request handling code. They’re the responsibility of the caller.

websockets.handshake.build_response(set_header, key)[source]

Build a handshake response to send to the client.

key comes from check_request().

websockets.handshake.check_response(get_header, key)[source]

Check a handshake response received from the server.

key comes from build_request().

If the handshake is valid, this function returns None.

Otherwise it raises an InvalidHandshake exception.

This function doesn’t verify that the response is an HTTP/1.1 or higher response with a 101 status code. These controls are the responsibility of the caller.

Data transfer

The websockets.framing module implements data framing as specified in section 5 of RFC 6455.

It deals with a single frame at a time. Anything that depends on the sequence of frames is implemented in websockets.protocol.

class websockets.framing.Frame

WebSocket frame.

  • fin is the FIN bit
  • opcode is the opcode
  • data is the payload data

Only these three fields are needed by higher level code. The MASK bit, payload length and masking-key are handled on the fly by read_frame() and write_frame().

data

Alias for field number 2

fin

Alias for field number 0

opcode

Alias for field number 1

websockets.framing.read_frame(reader, mask, *, max_size=None)[source]

Read a WebSocket frame and return a Frame object.

reader is a coroutine taking an integer argument and reading exactly this number of bytes, unless the end of file is reached.

mask is a bool telling whether the frame should be masked i.e. whether the read happens on the server side.

If max_size is set and the payload exceeds this size in bytes, PayloadTooBig is raised.

This function validates the frame before returning it and raises WebSocketProtocolError if it contains incorrect values.

websockets.framing.write_frame(frame, writer, mask)[source]

Write a WebSocket frame.

frame is the Frame object to write.

writer is a function accepting bytes.

mask is a bool telling whether the frame should be masked i.e. whether the write happens on the client side.

This function validates the frame before sending it and raises WebSocketProtocolError if it contains incorrect values.

websockets.framing.parse_close(data)[source]

Parse the data in a close frame.

Return (code, reason) when code is an int and reason a str.

Raise WebSocketProtocolError or UnicodeDecodeError if the data is invalid.

websockets.framing.serialize_close(code, reason)[source]

Serialize the data for a close frame.

This is the reverse of parse_close().

URI parser

The websockets.uri module implements parsing of WebSocket URIs according to section 3 of RFC 6455.

websockets.uri.parse_uri(uri)[source]

This function parses and validates a WebSocket URI.

If the URI is valid, it returns a WebSocketURI.

Otherwise it raises an InvalidURI exception.

class websockets.uri.WebSocketURI

WebSocket URI.

  • secure is the secure flag
  • host is the lower-case host
  • port if the integer port, it’s always provided even if it’s the default
  • resource_name is the resource name, that is, the path and optional query
host

Alias for field number 1

port

Alias for field number 2

resource_name

Alias for field number 3

secure

Alias for field number 0

Utilities

The websockets.http module provides HTTP parsing functions. They’re merely adequate for the WebSocket handshake messages.

These functions cannot be imported from websockets; they must be imported from websockets.http.

websockets.http.read_request(stream)[source]

Read an HTTP/1.1 GET request from stream.

stream is an StreamReader.

Return (path, headers) where path is a str and headers is a list of (name, value) tuples.

path isn’t URL-decoded or validated in any way.

Non-ASCII characters are represented with surrogate escapes.

Raise an exception if the request isn’t well formatted.

Don’t attempt to read the request body because WebSocket handshake requests don’t have one. If the request contains a body, it may be read from stream after this coroutine returns.

websockets.http.read_response(stream)[source]

Read an HTTP/1.1 response from stream.

stream is an StreamReader.

Return (status_code, headers) where status_code is a int and headers is a list of (name, value) tuples.

Non-ASCII characters are represented with surrogate escapes.

Raise an exception if the response isn’t well formatted.

Don’t attempt to read the response body, because WebSocket handshake responses don’t have one. If the response contains a body, it may be read from stream after this coroutine returns.