# stomp package

## Subpackages

- stomp.adapter package
  - Submodules
  - stomp.adapter.multicast module
    - `MulticastConnection`
      - `MulticastConnection.connect()`
      - `MulticastConnection.disconnect()`
      - `MulticastConnection.send_frame()`
      - `MulticastConnection.subscribe()`
      - `MulticastConnection.unsubscribe()`
    - `MulticastTransport`
      - `MulticastTransport.attempt_connection()`
      - `MulticastTransport.process_frame()`
      - `MulticastTransport.receive()`
      - `MulticastTransport.send()`
      - `MulticastTransport.stop()`
  - Module contents

## Submodules

## stomp.colours module

Colour ‘constants’ used by the command line client.

## stomp.connect module

Main entry point for clients to create a STOMP connection.

Provides connection classes for 1.0, 1.1, and 1.2 versions of the STOMP protocol.

class stomp.connect.BaseConnection(transport)

  Bases: `Publisher`

  Base class for all connection classes.

  disconnect(receipt=None, headers=None, **keyword_headers)
  get_listener(name)
    Parameters:

      name (str) –

    Return type:

      ConnectionListener

  get_ssl(host_and_port=None)
  is_connected()
    Return type:

      bool

  remove_listener(name)
    Parameters:

      name (str) –

  set_listener(name, listener)
    Parameters:

      - name (str) –

      - listener (ConnectionListener) –

  set_receipt(receipt_id, value)
  set_ssl(*args, **kwargs)

class stomp.connect.StompConnection10(host_and_ports=None, prefer_localhost=True, try_loopback_connect=True, reconnect_sleep_initial=0.1, reconnect_sleep_increase=0.5, reconnect_sleep_jitter=0.1, reconnect_sleep_max=60.0, reconnect_attempts_max=3, timeout=None, keepalive=None, auto_decode=True, encoding='utf-8', auto_content_length=True, bind_host_port=None)

  Bases: `BaseConnection`, `Protocol10`

  Represents a 1.0 connection (comprising transport plus 1.0 protocol class). See `stomp.transport.Transport` for details on the initialisation parameters.

  connect(*args, **kwargs)

    Start a connection.

    Parameters:

      - username (str) – the username to connect with

      - passcode (str) – the password used to authenticate with

      - wait (bool) – if True, wait for the connection to be established/acknowledged

      - headers (dict) – a map of any additional headers the broker requires

      - keyword_headers – any additional headers the broker requires

  disconnect(receipt=None, headers=None, **keyword_headers)

    Call the protocol disconnection, and then stop the transport itself.

    Parameters:

      - receipt (str) – the receipt to use with the disconnect

      - headers (dict) – a map of any additional headers to send with the disconnection

      - keyword_headers – any additional headers to send with the disconnection

class stomp.connect.StompConnection11(host_and_ports=None, prefer_localhost=True, try_loopback_connect=True, reconnect_sleep_initial=0.1, reconnect_sleep_increase=0.5, reconnect_sleep_jitter=0.1, reconnect_sleep_max=60.0, reconnect_attempts_max=3, timeout=None, heartbeats=(0, 0), keepalive=None, vhost=None, auto_decode=True, encoding='utf-8', auto_content_length=True, heart_beat_receive_scale=1.5, bind_host_port=None)

  Bases: `BaseConnection`, `Protocol11`

  Represents a 1.1 connection (comprising transport plus 1.1 protocol class) See `stomp.transport.Transport` for details on the initialisation parameters.

  connect(*args, **kwargs)

    Start a connection.

    Parameters:

      - username (str) – the username to connect with

      - passcode (str) – the password used to authenticate with

      - wait (bool) – if True, wait for the connection to be established/acknowledged

      - headers (dict) – a map of any additional headers the broker requires

      - with_connect_command – if True, use CONNECT command instead of STOMP

      - keyword_headers – any additional headers the broker requires

  disconnect(receipt=None, headers=None, **keyword_headers)

    Call the protocol disconnection, and then stop the transport itself.

    Parameters:

      - receipt (str) – the receipt to use with the disconnect

      - headers (dict) – a map of any additional headers to send with the disconnection

      - keyword_headers – any additional headers to send with the disconnection

class stomp.connect.StompConnection12(host_and_ports=None, prefer_localhost=True, try_loopback_connect=True, reconnect_sleep_initial=0.1, reconnect_sleep_increase=0.5, reconnect_sleep_jitter=0.1, reconnect_sleep_max=60.0, reconnect_attempts_max=3, timeout=None, heartbeats=(0, 0), keepalive=None, vhost=None, auto_decode=True, encoding='utf-8', auto_content_length=True, heart_beat_receive_scale=1.5, bind_host_port=None)

  Bases: `BaseConnection`, `Protocol12`

  Represents a 1.2 connection (comprising transport plus 1.2 protocol class). See `stomp.transport.Transport` for details on the initialisation parameters.

  connect(*args, **kwargs)

    Send a STOMP CONNECT frame. Differs from 1.0 and 1.1 versions in that the HOST header is enforced.

    Parameters:

      - username (str) – optionally specify the login user

      - passcode (str) – optionally specify the user password

      - wait (bool) – wait for the connection to complete before returning

      - headers (dict) – a map of any additional headers to send with the subscription

      - with_connect_command – if True, use CONNECT command instead of STOMP

      - keyword_headers – any additional headers to send with the subscription

  disconnect(receipt=None, headers=None, **keyword_headers)

    Call the protocol disconnection, and then stop the transport itself.

    Parameters:

      - receipt (str) – the receipt to use with the disconnect

      - headers (dict) – a map of any additional headers to send with the disconnection

      - keyword_headers – any additional headers to send with the disconnection

  static is_eol(c)

## stomp.constants module

The STOMP command and header name strings.

## stomp.exception module

Errors thrown by stomp.py connections.

exception stomp.exception.ConnectFailedException

  Bases: `StompException`

  Raised by Connection.attempt_connection when reconnection attempts have exceeded Connection.__reconnect_attempts_max.

exception stomp.exception.ConnectionClosedException

  Bases: `StompException`

  Raised in the receiver thread when the connection has been closed by the server.

exception stomp.exception.InterruptedException

  Bases: `StompException`

  Raised by receive when data read is interrupted.

exception stomp.exception.NotConnectedException

  Bases: `StompException`

  Raised when there is currently no server connection.

exception stomp.exception.StompException

  Bases: `Exception`

  Common exception class. All specific stomp.py exceptions are subclasses of StompException, allowing the library user to catch all current and future library exceptions.

## stomp.listener module

Various listeners for using with stomp.py connections.

class stomp.listener.ConnectionListener

  Bases: `object`

  This class should be used as a base class for objects registered using Connection.set_listener().

  on_before_message(frame)

    Called by the STOMP connection before a message is returned to the client app. Returns a tuple containing the headers and body (so that implementing listeners can pre-process the content).

    Parameters:

      frame (Frame) – the stomp frame

  on_connected(frame)

    Called by the STOMP connection when a CONNECTED frame is received (after a connection has been established or re-established).

    Parameters:

      frame (Frame) – the stomp frame

  on_connecting(host_and_port)

    Called by the STOMP connection once a TCP/IP connection to the STOMP server has been established or re-established. Note that at this point, no connection has been established on the STOMP protocol level. For this, you need to invoke the “connect” method on the connection.

    Parameters:

      host_and_port ((str,int)) – a tuple containing the host name and port number to which the connection has been established.

  on_disconnected()

    Called by the STOMP connection when a TCP/IP connection to the STOMP server has been lost. No messages should be sent via the connection until it has been reestablished.

  on_disconnecting()

    Called before a DISCONNECT frame is sent.

  on_error(frame)

    Called by the STOMP connection when an ERROR frame is received.

    Parameters:

      frame (Frame) – the stomp frame

  on_heartbeat()

    Called on receipt of a heartbeat.

  on_heartbeat_timeout()

    Called by the STOMP connection when a heartbeat message has not been received beyond the specified period.

  on_message(frame)

    Called by the STOMP connection when a MESSAGE frame is received.

    Parameters:

      frame (Frame) – the stomp frame

  on_receipt(frame)

    Called by the STOMP connection when a RECEIPT frame is received, sent by the server if requested by the client using the ‘receipt’ header.

    Parameters:

      frame (Frame) – the stomp frame

  on_receiver_loop_completed(frame)

    Called when the connection receiver_loop has finished.

  on_send(frame)

    Called by the STOMP connection when it is in the process of sending a message

    Parameters:

      frame (Frame) – the stomp frame

class stomp.listener.HeartbeatListener(transport, heartbeats, heart_beat_receive_scale=1.5)

  Bases: `ConnectionListener`

  Listener used to handle STOMP heartbeating.

  on_connected(frame)

    Once the connection is established, and ‘heart-beat’ is found in the headers, we calculate the real heartbeat numbers (based on what the server sent and what was specified by the client) - if the heartbeats are not 0, we start up the heartbeat loop accordingly.

    Parameters:

      frame (Frame) – the stomp frame

  on_disconnected()

    Called by the STOMP connection when a TCP/IP connection to the STOMP server has been lost. No messages should be sent via the connection until it has been reestablished.

  on_disconnecting()

    Called before a DISCONNECT frame is sent.

  on_error(*_)

    Reset the last received time whenever an error is received.

  on_heartbeat()

    Reset the last received time whenever a heartbeat message is received.

  on_message(frame)

    Reset the last received time whenever a message is received.

    Parameters:

      frame (Frame) – the stomp frame

  on_receipt(*_)

    Reset the last received time whenever a receipt is received.

  on_send(frame)

    Add the heartbeat header to the frame when connecting, and bump next outbound heartbeat timestamp.

    Parameters:

      frame (Frame) – the Frame object

class stomp.listener.PrintingListener(print_to_log=False)

  Bases: `ConnectionListener`

  on_before_message(frame)
    Parameters:

      frame (Frame) – the stomp frame

  on_connected(frame)
    Parameters:

      frame (Frame) – the stomp frame

  on_connecting(host_and_port)
    Parameters:

      host_and_port ((str,int)) –

  on_disconnected()

    Called by the STOMP connection when a TCP/IP connection to the STOMP server has been lost. No messages should be sent via the connection until it has been reestablished.

  on_error(frame)
    Parameters:

      frame (Frame) – the stomp frame

  on_heartbeat()

    Called on receipt of a heartbeat.

  on_heartbeat_timeout()

    Called by the STOMP connection when a heartbeat message has not been received beyond the specified period.

  on_message(frame)
    Parameters:

      frame (Frame) – the stomp frame

  on_receipt(frame)
    Parameters:

      frame (Frame) – the stomp frame

  on_send(frame)
    Parameters:

      frame (Frame) – the stomp frame

class stomp.listener.Publisher

  Bases: `object`

  Simply a registry of listeners.

  get_listener(name)

    Return the named listener.

    Parameters:

      name (str) – the listener to return

    Return type:

      ConnectionListener

  remove_listener(name)

    Remove a listener.

    Parameters:

      name (str) – the name of the listener to remove

  set_listener(name, listener)

    Set a named listener to use with this connection. See `stomp.listener.ConnectionListener`

    Parameters:

      - name (str) – the name of the listener

      - listener (ConnectionListener) – the listener object

class stomp.listener.StatsListener

  Bases: `ConnectionListener`

  A connection listener for recording statistics on messages sent and received.

  on_connecting(host_and_port)

    Increment the connection count. See `ConnectionListener.on_connecting()`

    Parameters:

      host_and_port ((str,int)) – the host and port as a tuple

  on_disconnected()

    Increment the disconnect count. See `ConnectionListener.on_disconnected()`

  on_error(frame)

    Increment the error count. See `ConnectionListener.on_error()`

    Parameters:

      frame (Frame) – the stomp frame

  on_heartbeat()

    Increment the heartbeat count. See `ConnectionListener.on_heartbeat()`

  on_heartbeat_timeout()

    Increment the heartbeat timeout. See `ConnectionListener.on_heartbeat_timeout()`

  on_message(frame)

    Increment the message received count. See `ConnectionListener.on_message()`

    Parameters:

      frame (Frame) – the stomp frame

  on_send(frame)

    Increment the send count. See `ConnectionListener.on_send()`

    Parameters:

      frame (Frame) –

class stomp.listener.TestListener(receipt=None, print_to_log=False)

  Bases: `StatsListener`, `WaitingListener`, `PrintingListener`

  Implementation of StatsListener and WaitingListener. Useful for testing.

  get_latest_message()
  on_before_message(frame)

    Called by the STOMP connection before a message is returned to the client app. Returns a tuple containing the headers and body (so that implementing listeners can pre-process the content).

    Parameters:

      frame (Frame) – the stomp frame

  on_connected(frame)

    Called by the STOMP connection when a CONNECTED frame is received (after a connection has been established or re-established).

    Parameters:

      frame (Frame) – the stomp frame

  on_connecting(host_and_port)

    Increment the connection count. See `ConnectionListener.on_connecting()`

    Parameters:

      host_and_port ((str,int)) – the host and port as a tuple

  on_disconnected()

    Increment the disconnect count. See `ConnectionListener.on_disconnected()`

  on_error(frame)

    Increment the error count. See `ConnectionListener.on_error()`

    Parameters:

      frame (Frame) – the stomp frame

  on_heartbeat()

    Increment the heartbeat count. See `ConnectionListener.on_heartbeat()`

  on_heartbeat_timeout()

    Increment the heartbeat timeout. See `ConnectionListener.on_heartbeat_timeout()`

  on_message(frame)
    Parameters:

      frame (Frame) – the stomp frame

  on_receipt(frame)

    Called by the STOMP connection when a RECEIPT frame is received, sent by the server if requested by the client using the ‘receipt’ header.

    Parameters:

      frame (Frame) – the stomp frame

  on_receiver_loop_completed(frame)

    Called when the connection receiver_loop has finished.

  on_send(frame)

    Increment the send count. See `ConnectionListener.on_send()`

    Parameters:

      frame (Frame) –

  wait_for_heartbeat()
  wait_for_message()

class stomp.listener.WaitingListener(receipt)

  Bases: `ConnectionListener`

  A listener which waits for a specific receipt to arrive.

  on_disconnected()

    Called by the STOMP connection when a TCP/IP connection to the STOMP server has been lost. No messages should be sent via the connection until it has been reestablished.

  on_receipt(frame)

    If the receipt id can be found in the headers, then notify the waiting thread.

    Parameters:

      frame (Frame) – the stomp frame

  wait_on_disconnected()

    Wait until disconnected.

  wait_on_receipt()

    Wait until we receive a message receipt.

## stomp.protocol module

Provides the 1.0, 1.1 and 1.2 protocol classes.

class stomp.protocol.Protocol10(transport, auto_content_length=True)

  Bases: `ConnectionListener`

  Represents version 1.0 of the protocol (see https://stomp.github.io/stomp-specification-1.0.html).

  Most users should not instantiate the protocol directly. See `stomp.connect` for connection classes.

  Parameters:

    - transport –

    - auto_content_length (bool) – Whether to calculate and send the content-length header

  automatically if it has not been set

  abort(transaction, headers=None, **keyword_headers)

    Abort a transaction.

    Parameters:

      - transaction (str) – the identifier of the transaction

      - headers (dict) – a map of any additional headers the broker requires

      - keyword_headers – any additional headers the broker requires

  ack(id, transaction=None, receipt=None)

    Acknowledge ‘consumption’ of a message by id.

    Parameters:

      - id (str) – identifier of the message

      - transaction (str) – include the acknowledgement in the specified transaction

      - receipt (str) – the receipt id

  begin(transaction=None, headers=None, **keyword_headers)

    Begin a transaction.

    Parameters:

      - transaction (str) – the identifier for the transaction (optional - if not specified a unique transaction id will be generated)

      - headers (dict) – a map of any additional headers the broker requires

      - keyword_headers – any additional headers the broker requires

    Returns:

      the transaction id

    Return type:

      str

  commit(transaction=None, headers=None, **keyword_headers)

    Commit a transaction.

    Parameters:

      - transaction (str) – the identifier for the transaction

      - headers (dict) – a map of any additional headers the broker requires

      - keyword_headers – any additional headers the broker requires

  connect(username=None, passcode=None, wait=False, headers=None, **keyword_headers)

    Start a connection.

    Parameters:

      - username (str) – the username to connect with

      - passcode (str) – the password used to authenticate with

      - wait (bool) – if True, wait for the connection to be established/acknowledged

      - headers (dict) – a map of any additional headers the broker requires

      - keyword_headers – any additional headers the broker requires

  disconnect(receipt=None, headers=None, **keyword_headers)

    Disconnect from the server.

    Parameters:

      - receipt (str) – the receipt to use (once the server acknowledges that receipt, we’re officially disconnected; optional - if not specified a unique receipt id will be generated)

      - headers (dict) – a map of any additional headers the broker requires

      - keyword_headers – any additional headers the broker requires

  send(destination, body, content_type=None, headers=None, **keyword_headers)

    Send a message to a destination.

    Parameters:

      - destination (str) – the destination of the message (e.g. queue or topic name)

      - body – the content of the message

      - content_type (str) – the content type of the message

      - headers (dict) – a map of any additional headers the broker requires

      - keyword_headers – any additional headers the broker requires

  send_frame(cmd, headers=None, body='')

    Encode and send a stomp frame through the underlying transport.

    Parameters:

      - cmd (str) – the protocol command

      - headers (dict) – a map of headers to include in the frame

      - body – the content of the message

  subscribe(destination, id=None, ack='auto', headers=None, **keyword_headers)

    Subscribe to a destination.

    Parameters:

      - destination (str) – the topic or queue to subscribe to

      - id (str) – a unique id to represent the subscription

      - ack (str) – acknowledgement mode, either auto, client, or client-individual (see http://stomp.github.io/stomp-specification-1.2.html#SUBSCRIBE_ack_Header) for more information

      - headers (dict) – a map of any additional headers the broker requires

      - keyword_headers – any additional headers the broker requires

  unsubscribe(destination=None, id=None, headers=None, **keyword_headers)

    Unsubscribe from a destination by either id or the destination name.

    Parameters:

      - destination (str) – the name of the topic or queue to unsubscribe from

      - id (str) – the unique identifier of the topic or queue to unsubscribe from

      - headers (dict) – a map of any additional headers the broker requires

      - keyword_headers – any additional headers the broker requires

class stomp.protocol.Protocol11(transport, heartbeats=(0, 0), auto_content_length=True, heart_beat_receive_scale=1.5)

  Bases: `HeartbeatListener`, `ConnectionListener`

  Represents version 1.1 of the protocol (see https://stomp.github.io/stomp-specification-1.1.html).

  Most users should not instantiate the protocol directly. See `stomp.connect` for connection classes.

  Parameters:

    - transport –

    - heartbeats ((int,int)) –

    - auto_content_length (bool) – Whether to calculate and send the content-length header

  automatically if it has not been set :param float heart_beat_receive_scale: how long to wait for a heartbeat before timing out, as a scale factor of receive time

  abort(transaction, headers=None, **keyword_headers)

    Abort a transaction.

    Parameters:

      - transaction (str) – the identifier of the transaction

      - headers (dict) – a map of any additional headers the broker requires

      - keyword_headers – any additional headers the broker requires

  ack(id, subscription, transaction=None, receipt=None)

    Acknowledge ‘consumption’ of a message by id.

    Parameters:

      - id (str) – identifier of the message

      - subscription (str) – the subscription this message is associated with

      - transaction (str) – include the acknowledgement in the specified transaction

      - receipt (str) – the receipt id

  begin(transaction=None, headers=None, **keyword_headers)

    Begin a transaction.

    Parameters:

      - transaction (str) – the identifier for the transaction (optional - if not specified a unique transaction id will be generated)

      - headers (dict) – a map of any additional headers the broker requires

      - keyword_headers – any additional headers the broker requires

    Returns:

      the transaction id

    Return type:

      str

  commit(transaction=None, headers=None, **keyword_headers)

    Commit a transaction.

    Parameters:

      - transaction (str) – the identifier for the transaction

      - headers (dict) – a map of any additional headers the broker requires

      - keyword_headers – any additional headers the broker requires

  connect(username=None, passcode=None, wait=False, headers=None, with_connect_command=False, **keyword_headers)

    Start a connection.

    Parameters:

      - username (str) – the username to connect with

      - passcode (str) – the password used to authenticate with

      - wait (bool) – if True, wait for the connection to be established/acknowledged

      - headers (dict) – a map of any additional headers the broker requires

      - with_connect_command – if True, use CONNECT command instead of STOMP

      - keyword_headers – any additional headers the broker requires

  disconnect(receipt=None, headers=None, **keyword_headers)

    Disconnect from the server.

    Parameters:

      - receipt (str) – the receipt to use (once the server acknowledges that receipt, we’re officially disconnected; optional - if not specified a unique receipt id will be generated)

      - headers (dict) – a map of any additional headers the broker requires

      - keyword_headers – any additional headers the broker requires

  nack(id, subscription, transaction=None, receipt=None, **keyword_headers)

    Let the server know that a message was not consumed.

    Parameters:

      - id (str) – the unique id of the message to nack

      - subscription (str) – the subscription this message is associated with

      - transaction (str) – include this nack in a named transaction

      - receipt (str) – the receipt id

      - keyword_headers – any additional headers to send with the nack command

  send(destination, body, content_type=None, headers=None, **keyword_headers)
    Send a message to a destination in the messaging system (as per

      https://stomp.github.io/stomp-specification-1.2.html#SEND)

    Parameters:

      destination (str) – the destination (such as a message queue - for example

    ‘/queue/test’ - or a message topic) :param body: the content of the message :param str content_type: the MIME type of message :param dict headers: additional headers to send in the message frame :param keyword_headers: any additional headers the broker requires

  send_frame(cmd, headers=None, body='')

    Encode and send a stomp frame through the underlying transport:

    Parameters:

      - cmd (str) – the protocol command

      - headers (dict) – a map of headers to include in the frame

      - body – the content of the message

  subscribe(destination, id, ack='auto', headers=None, **keyword_headers)

    Subscribe to a destination

    Parameters:

      - destination (str) – the topic or queue to subscribe to

      - id (str) – the identifier to uniquely identify the subscription

      - ack (str) – either auto, client or client-individual

    (see https://stomp.github.io/stomp-specification-1.2.html#SUBSCRIBE for more info) :param dict headers: a map of any additional headers to send with the subscription :param keyword_headers: any additional headers to send with the subscription

  unsubscribe(id, headers=None, **keyword_headers)

    Unsubscribe from a destination by its unique identifier

    Parameters:

      - id (str) – the unique identifier to unsubscribe from

      - headers (dict) – additional headers to send with the unsubscribe

      - keyword_headers – any additional headers to send with the subscription

class stomp.protocol.Protocol12(transport, heartbeats=(0, 0), auto_content_length=True, heart_beat_receive_scale=1.5)

  Bases: `Protocol11`

  Represents version 1.2 of the protocol (see https://stomp.github.io/stomp-specification-1.2.html).

  Most users should not instantiate the protocol directly. See `stomp.connect` for connection classes.

  Parameters:

    - transport –

    - heartbeats ((int,int)) –

    - auto_content_length (bool) – Whether to calculate and send the content-length header

  automatically if it has not been set :param float heart_beat_receive_scale: how long to wait for a heartbeat before timing out, as a scale factor of receive time

  ack(id, transaction=None, receipt=None)

    Acknowledge ‘consumption’ of a message by id.

    Parameters:

      - id (str) – identifier of the message

      - transaction (str) – include the acknowledgement in the specified transaction

      - receipt (str) – the receipt id

  connect(username=None, passcode=None, wait=False, headers=None, with_connect_command=False, **keyword_headers)

    Send a STOMP CONNECT frame. Differs from 1.0 and 1.1 versions in that the HOST header is enforced.

    Parameters:

      - username (str) – optionally specify the login user

      - passcode (str) – optionally specify the user password

      - wait (bool) – wait for the connection to complete before returning

      - headers (dict) – a map of any additional headers to send with the subscription

      - with_connect_command – if True, use CONNECT command instead of STOMP

      - keyword_headers – any additional headers to send with the subscription

  nack(id, transaction=None, receipt=None, **keyword_headers)

    Let the server know that a message was not consumed.

    Parameters:

      - id (str) – the unique id of the message to nack

      - transaction (str) – include this nack in a named transaction

      - receipt (str) – the receipt id

      - keyword_headers – any additional headers to send with the nack command

## stomp.transport module

Provides the underlying transport functionality (for stomp message transmission) - (mostly) independent from the actual STOMP protocol

class stomp.transport.BaseTransport(auto_decode=True, encoding='utf-8', is_eol_fc=<function is_eol_default>)

  Bases: `Publisher`

  Base class for transport classes providing support for listeners, threading overrides, and anything else outside of actually establishing a network connection, sending and receiving of messages (so generally socket-agnostic functions).

  Parameters:

    - auto_decode (bool) – automatically decode message responses as strings, rather than leaving them as bytes. This preserves the behaviour as of version 4.0.16. (To be defaulted to False as of the next release)

    - encoding – the character encoding to use for the message body

  attempt_connection()

    Attempt to establish a connection.

  cleanup()

    Cleanup the transport (to be implemented in subclasses)

  disconnect_socket()

    Disconnect the socket.

  get_listener(name)

    Return the named listener

    Parameters:

      name (str) – the listener to return

    Return type:

      ConnectionListener

  is_connected()
    Return type:

      bool

  notify(frame_type, frame=None)

    Utility function for notifying listeners of incoming and outgoing messages

    Parameters:

      - frame_type (str) – the type of message

      - frame (Frame) – the stomp frame

  override_threading(create_thread_fc)

    Override for thread creation. Use an alternate threading library by setting this to a function with a single argument (which is the receiver loop callback). The thread which is returned should be started (ready to run)

    Parameters:

      create_thread_fc (function) – single argument function for creating a thread

  process_frame(f, frame_str)
    Parameters:

      - f (Frame) – Frame object

      - frame_str (bytes) – raw frame content

  receive()

    Receive a chunk of data (to be implemented in subclasses)

    Return type:

      bytes

  remove_listener(name)

    Remove a listener according to the specified name

    Parameters:

      name (str) – the name of the listener to remove

  send(encoded_frame)

    Send an encoded frame over this transport (to be implemented in subclasses)

    Parameters:

      encoded_frame (bytes) – a Frame object which has been encoded for transmission

  set_connected(connected)
    Parameters:

      connected (bool) –

  set_listener(name, listener)

    Set a named listener to use with this connection. See `stomp.listener.ConnectionListener`

    Parameters:

      - name (str) – the name of the listener

      - listener (ConnectionListener) – the listener object

  set_receipt(receipt_id, value)
  start()

    Start the connection. This should be called after all listeners have been registered. If this method is not called, no frames will be received by the connection and no SSL/TLS handshake will occur.

  stop()

    Stop the connection. Performs a clean shutdown by waiting for the receiver thread to exit.

  transmit(frame)

    Convert a frame object to a frame string and transmit to the server.

    Parameters:

      frame (Frame) – the Frame object to transmit

  wait_for_connection(timeout=None)

    Wait until we’ve established a connection with the server.

    Parameters:

      timeout (float) – how long to wait, in seconds

class stomp.transport.Transport(host_and_ports=None, prefer_localhost=True, try_loopback_connect=True, reconnect_sleep_initial=0.1, reconnect_sleep_increase=0.5, reconnect_sleep_jitter=0.1, reconnect_sleep_max=60.0, reconnect_attempts_max=3, timeout=None, keepalive=None, vhost=None, auto_decode=True, encoding='utf-8', recv_bytes=1024, is_eol_fc=<function is_eol_default>, bind_host_port=None)

  Bases: `BaseTransport`

  Represents a STOMP client ‘transport’. Effectively this is the communications mechanism without the definition of the protocol.

  Parameters:

    - host_and_ports (list((str,int))) – a list of (host, port) tuples

    - prefer_localhost (bool) – if True and the local host is mentioned in the (host, port) tuples, try to connect to this first

    - try_loopback_connect (bool) – if True and the local host is found in the host tuples, try connecting to it using loopback interface (127.0.0.1)

    - reconnect_sleep_initial (float) – initial delay in seconds to wait before reattempting to establish a connection if connection to any of the hosts fails.

    - reconnect_sleep_increase (float) – factor by which the sleep delay is increased after each connection attempt. For example, 0.5 means to wait 50% longer than before the previous attempt, 1.0 means wait twice as long, and 0.0 means keep the delay constant.

    - reconnect_sleep_max (float) – maximum delay between connection attempts, regardless of the reconnect_sleep_increase.

    - reconnect_sleep_jitter (float) – random additional time to wait (as a percentage of the time determined using the previous parameters) between connection attempts in order to avoid stampeding. For example, a value of 0.1 means to wait an extra 0%-10% (randomly determined) of the delay calculated using the previous three parameters.

    - reconnect_attempts_max (int) – maximum attempts to reconnect (Can also be used for infinite attempts : -1)

    - timeout – the timeout value to use when connecting the stomp socket

    - keepalive – some operating systems support sending the occasional heart beat packets to detect when a connection fails. This parameter can either be set set to a boolean to turn on the default keepalive options for your OS, or as a tuple of values, which also enables keepalive packets, but specifies options specific to your OS implementation. For linux, supply (“linux”, ka_idle, ka_intvl, ka_cnt) For macos, supply (“mac”, ka_intvl)

    - vhost (str) – specify a virtual hostname to provide in the ‘host’ header of the connection

    - recv_bytes (int) – the number of bytes to use when calling recv

  attempt_connection()

    Try connecting to the (host, port) tuples specified at construction time.

  cleanup()

    Close the socket and clear the current host and port details.

  disconnect_socket()

    Disconnect the underlying socket connection

  get_ssl(host_and_port=None)

    Get SSL params for the given host.

    Parameters:

      host_and_port ((str,int)) – the host/port pair we want SSL params for, default current_host_and_port

  is_connected()

    Return true if the socket managed by this connection is connected

    Return type:

      bool

  receive()
    Return type:

      bytes

  send(encoded_frame)
    Parameters:

      encoded_frame (bytes) –

  set_ssl(for_hosts=[], key_file=None, cert_file=None, ca_certs=None, cert_validator=None, ssl_version=_SSLMethod.PROTOCOL_TLS_CLIENT, password=None)

    Sets up SSL configuration for the given hosts. This ensures socket is wrapped in a SSL connection, raising an exception if the SSL module can’t be found.

    Parameters:

      - for_hosts – a list of tuples describing hosts this SSL configuration should be applied to

      - cert_file – the path to a X509 certificate

      - key_file – the path to a X509 key file

      - ca_certs – the path to the a file containing CA certificates to validate the server against. If this is not set, server side certificate validation is not done.

      - cert_validator – function which performs extra validation on the client certificate, for example checking the returned certificate has a commonName attribute equal to the hostname (to avoid man in the middle attacks). The signature is: (OK, err_msg) = validation_function(cert, hostname) where OK is a boolean, and cert is a certificate structure as returned by ssl.SSLSocket.getpeercert()

      - ssl_version – SSL protocol to use for the connection. This should be one of the PROTOCOL_x constants provided by the ssl module. The default is ssl.PROTOCOL_TLSv1

      - password – SSL password

## stomp.utils module

General utility functions.

class stomp.utils.Frame(cmd, headers=None, body=None)

  Bases: `object`

  A STOMP frame (or message).

  Parameters:

    - cmd (str) – the protocol command

    - headers (dict) – a map of headers for the frame

    - body – the content of the frame.

stomp.utils.calculate_heartbeats(shb, chb)

  Given a heartbeat string from the server, and a heartbeat tuple from the client, calculate what the actual heartbeat settings should be.

  Parameters:

    - shb ((str,str)) – server heartbeat numbers

    - chb ((int,int)) – client heartbeat numbers

  Return type:

    (int,int)

stomp.utils.clean_headers(headers)

stomp.utils.clean_lines(lines)

stomp.utils.convert_frame(frame)

  Convert a frame to a list of lines separated by newlines.

  Parameters:

    frame (Frame) – the Frame object to convert

  Return type:

    list(str)

stomp.utils.decode(byte_data, encoding='utf-8')

  Decode the byte data to a string if not None.

  Parameters:

    - byte_data (bytes) – the data to decode

    - encoding (string) – character encoding

  Return type:

    str

stomp.utils.default_create_thread(callback)

  Default thread creation - used to create threads when the client doesn’t want to provide their own thread creation.

  Parameters:

    callback (function) – the callback function provided to threading.Thread

stomp.utils.encode(char_data, encoding='utf-8')

  Encode the parameter as a byte string.

  Parameters:

    - char_data – the data to encode

    - encoding (string) – character encoding

  Return type:

    bytes

stomp.utils.get_errno(e)

  Return the errno of an exception, or the first argument if errno is not available.

  Parameters:

    e (Exception) – the exception object

stomp.utils.get_uuid()

stomp.utils.is_eol_default(c)

stomp.utils.is_localhost(host_and_port)

  Return 1 if the specified host+port is a member of the ‘localhost’ list of hosts, 2 if not (predominately used as a sort key.

  Parameters:

    host_and_port ((str,int)) – tuple containing host and port

  Return type:

    int

stomp.utils.join(chars=())

  Join a sequence of characters into a string.

  Parameters:

    chars (bytes) – list of chars

  Return type:

    str

stomp.utils.length(s)

  Null (none) safe length function.

  Parameters:

    s (str) – the string to return length of (None allowed)

  Return type:

    int

stomp.utils.merge_headers(header_map_list)

  Helper function for combining multiple header maps into one.

  Parameters:

    header_map_list (list(dict)) – list of maps

  Return type:

    dict

stomp.utils.pack(pieces=())

  Join a sequence of strings together.

  Parameters:

    pieces (list) – list of strings

  Return type:

    bytes

stomp.utils.parse_frame(frame)

  Parse a STOMP frame into a Frame object.

  Parameters:

    frame (bytes) – the frame received from the server (as a byte string)

  Return type:

    Frame

stomp.utils.parse_headers(lines, offset=0)

  Parse the headers in a STOMP response

  Parameters:

    - lines (list(str)) – the lines received in the message response

    - offset (int) – the starting line number

  Return type:

    dict(str,str)

## Module contents

stomp.py provides connectivity to a message broker supporting the STOMP protocol. Protocol versions 1.0, 1.1 and 1.2 are supported.

See the GITHUB project page for more information.

Author: Jason R Briggs
License: http://www.apache.org/licenses/LICENSE-2.0
Project Page: https://github.com/jasonrbriggs/stomp.py