Extensions

The WebSocket protocol supports extensions.

At the time of writing, there’s only one registered extension with a public specification, WebSocket Per-Message Deflate.

Per-Message Deflate

websockets.extensions.permessage_deflate implements WebSocket Per-Message Deflate.

This extension is specified in RFC 7692.

Refer to the topic guide on compression to learn more about tuning compression settings.

class websockets.extensions.permessage_deflate.ClientPerMessageDeflateFactory(server_no_context_takeover=False, client_no_context_takeover=False, server_max_window_bits=None, client_max_window_bits=True, compress_settings=None)

Client-side extension factory for the Per-Message Deflate extension.

Parameters behave as described in section 7.1 of RFC 7692.

Set them to True to include them in the negotiation offer without a value or to an integer value to include them with this value.

Parameters:

• server_no_context_takeover (bool) – Prevent server from using context takeover.

• client_no_context_takeover (bool) – Prevent client from using context takeover.

• server_max_window_bits (int | None) – Maximum size of the server’s LZ77 sliding window in bits, between 8 and 15.

• client_max_window_bits (int | bool | None) – Maximum size of the client’s LZ77 sliding window in bits, between 8 and 15, or True to indicate support without setting a limit.

• compress_settings (dict[str, Any] | None) – Additional keyword arguments for zlib.compressobj(), excluding wbits.

class websockets.extensions.permessage_deflate.ServerPerMessageDeflateFactory(server_no_context_takeover=False, client_no_context_takeover=False, server_max_window_bits=None, client_max_window_bits=None, compress_settings=None, require_client_max_window_bits=False)

Server-side extension factory for the Per-Message Deflate extension.

Parameters behave as described in section 7.1 of RFC 7692.

Set them to True to include them in the negotiation offer without a value or to an integer value to include them with this value.

Parameters:

• server_no_context_takeover (bool) – Prevent server from using context takeover.

• client_no_context_takeover (bool) – Prevent client from using context takeover.

• server_max_window_bits (int | None) – Maximum size of the server’s LZ77 sliding window in bits, between 8 and 15.

• client_max_window_bits (int | None) – Maximum size of the client’s LZ77 sliding window in bits, between 8 and 15.

• compress_settings (dict[str, Any] | None) – Additional keyword arguments for zlib.compressobj(), excluding wbits.

• require_client_max_window_bits (bool) – Do not enable compression at all if client doesn’t advertise support for client_max_window_bits; the default behavior is to enable compression without enforcing client_max_window_bits.

Base classes

websockets.extensions defines base classes for implementing

extensions.

Refer to the how-to guide on extensions to learn more about writing an extension.

class websockets.extensions.Extension

Base class for extensions.

name: ExtensionName

Extension identifier.

decode(frame, *, max_size=None)

Decode an incoming frame.

Parameters:

• frame (Frame) – Incoming frame.

• max_size (int | None) – Maximum payload size in bytes.

Returns:

Decoded frame.

Raises:

PayloadTooBig – If decoding the payload exceeds max_size.

Return type:

Frame

encode(frame)

Encode an outgoing frame.

Parameters:

frame (Frame) – Outgoing frame.

Returns:

Encoded frame.

Return type:

Frame

class websockets.extensions.ClientExtensionFactory

Base class for client-side extension factories.

name: ExtensionName

Extension identifier.

get_request_params()

Build parameters to send to the server for this extension.

Returns:

Parameters to send to the server.

Return type:

list[tuple[str, str | None]]

process_response_params(params, accepted_extensions)

Process parameters received from the server.

Parameters:

• params (Sequence[tuple[str, str | None]]) – Parameters received from the server for this extension.

• accepted_extensions (Sequence[Extension]) – List of previously accepted extensions.

Returns:

An extension instance.

Raises:

NegotiationError – If parameters aren’t acceptable.

Return type:

Extension

class websockets.extensions.ServerExtensionFactory

Base class for server-side extension factories.

process_request_params(params, accepted_extensions)

Process parameters received from the client.

Parameters:

• params (Sequence[tuple[str, str | None]]) – Parameters received from the client for this extension.

• accepted_extensions (Sequence[Extension]) – List of previously accepted extensions.

Returns:

To accept the offer, parameters to send to the client for this extension and an extension instance.

Raises:

NegotiationError – To reject the offer, if parameters received from the client aren’t acceptable.

Return type:

tuple[list[tuple[str, str | None]], Extension]