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)[source]#

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 (Optional[int]) – maximum size of the server’s LZ77 sliding window in bits, between 8 and 15.

  • client_max_window_bits (Optional[Union[int, bool]]) – 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 (Optional[Dict[str, Any]]) – 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)[source]#

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 (Optional[int]) – maximum size of the server’s LZ77 sliding window in bits, between 8 and 15.

  • client_max_window_bits (Optional[int]) – maximum size of the client’s LZ77 sliding window in bits, between 8 and 15.

  • compress_settings (Optional[Dict[str, Any]]) – 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[source]#

Base class for extensions.

name: ExtensionName#

Extension identifier.

decode(frame, *, max_size=None)[source]#

Decode an incoming frame.

Parameters:

  • frame (Frame) – incoming frame.

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

Returns:

Decoded frame.

Return type:

Frame

Raises:

PayloadTooBig – if decoding the payload exceeds max_size.

encode(frame)[source]#

Encode an outgoing frame.

Parameters:

frame (Frame) – outgoing frame.

Returns:

Encoded frame.

Return type:

Frame

class websockets.extensions.ClientExtensionFactory[source]#

Base class for client-side extension factories.

name: ExtensionName#

Extension identifier.

get_request_params()[source]#

Build parameters to send to the server for this extension.

Returns:

Parameters to send to the server.

Return type:

List[ExtensionParameter]

process_response_params(params, accepted_extensions)[source]#

Process parameters received from the server.

Parameters:

  • params (Sequence[ExtensionParameter]) – parameters received from the server for this extension.

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

Returns:

An extension instance.

Return type:

Extension

Raises:

NegotiationError – if parameters aren’t acceptable.

class websockets.extensions.ServerExtensionFactory[source]#

Base class for server-side extension factories.

process_request_params(params, accepted_extensions)[source]#

Process parameters received from the client.

Parameters:

  • params (Sequence[ExtensionParameter]) – 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.

Return type:

Tuple[List[ExtensionParameter], Extension]

Raises:

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