websocket

Description

Plugin to send and receive messages over websocket connections.

Configuration

websocket:
  # [Optional]
  # List of websocket URLs that should be subscribed
  # at startup, prefixed by ``ws://`` or ``wss://``.
  # subscriptions:   # type=Optional[Collection[str]]

  # [Optional]
  # How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
  # executed (default: 15 seconds). *NOTE*: For back-compatibility
  # reasons, the `poll_seconds` argument is also supported, but it's
  # deprecated.
  # poll_interval: 15  # type=Optional[float]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Triggered events

• platypush.message.event.websocket.WebsocketMessageEvent

Actions

• websocket.recv

• websocket.send

Module reference

class platypush.plugins.websocket.WebsocketPlugin(subscriptions: Collection[str] | None = None, **kwargs)

Bases: AsyncRunnablePlugin

Plugin to send and receive messages over websocket connections.

__init__(subscriptions: Collection[str] | None = None, **kwargs)

Parameters:

subscriptions – List of websocket URLs that should be subscribed at startup, prefixed by ws:// or wss://.

async listen()

Main body of the async plugin. When it’s called, the event loop should already be running and available over self._loop.

main()

Implementation of the main loop of the plugin.

recv(url: str, ssl_cert=None, ssl_key=None, ssl_cafile=None, ssl_capath=None, num_messages=0, timeout=0)

Receive one or more messages from a websocket.

A platypush.message.event.websocket.WebsocketMessageEvent event will be triggered whenever a new message is received.

Parameters:

• url – Websocket URL, e.g. ws://localhost:8765 or wss://localhost:8765

• ssl_cert – Path to the SSL certificate to be used, if the SSL connection requires client authentication as well (default: None)

• ssl_key – Path to the SSL key to be used, if the SSL connection requires client authentication as well (default: None)

• ssl_cafile – Path to the certificate authority file if required by the SSL configuration (default: None)

• ssl_capath – Path to the certificate authority directory if required by the SSL configuration (default: None)

• num_messages – Exit after receiving this number of messages. Default: 0, receive forever.

• timeout – Message receive timeout in seconds. Default: 0 - no timeout.

Returns:

A list with the messages that have been received, unless num_messages is set to 0 or None.

send(url: str, msg, ssl_cert=None, ssl_key=None, ssl_cafile=None, ssl_capath=None, wait_response=False, timeout=None)

Sends a message to a websocket.

Parameters:

• url – Websocket URL, e.g. ws://localhost:8765 or wss://localhost:8765

• msg – Message to be sent. It can be a list, a dict, or a Message object

• ssl_cert – Path to the SSL certificate to be used, if the SSL connection requires client authentication as well (default: None)

• ssl_key – Path to the SSL key to be used, if the SSL connection requires client authentication as well (default: None)

• ssl_cafile – Path to the certificate authority file if required by the SSL configuration (default: None)

• ssl_capath – Path to the certificate authority directory if required by the SSL configuration (default: None)

• wait_response – Set to True if you expect a response to the delivered message.

• timeout – If wait_response=True, then timeout establishes how long we should wait for a response before returning (default: no timeout).

Returns:

The received response if wait_response is set to True, otherwise nothing.

start()

Start the plugin.

stop()

Stop the plugin.

wait_stop(timeout=None)

Wait until a stop event is received.