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)[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, or True to indicate support without setting a limit.

  • compress_settings (Optional[Dict[str, Any]]) – additional keyword arguments for zlib.compressobj(), excluding wbits.

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: websockets.typing.ExtensionName

Extension identifier.

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

Decode an incoming frame.

Parameters
  • frame (Frame) – incoming frame.

  • max_size (Optional[int]) – 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: websockets.typing.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.