# stomp package

## Subpackages

- stomp.adapter package
  - Submodules
  - stomp.adapter.multicast module
  - 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: `stomp.listener.Publisher`

  Base class for all connection classes.

  `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, lstnr)
    Parameters

      - name (str) –

      - lstnr (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, use_ssl=False, ssl_key_file=None, ssl_cert_file=None, ssl_ca_certs=None, ssl_cert_validator=None, ssl_version=<_SSLMethod.PROTOCOL_TLSv1: 3>, timeout=None, keepalive=None, auto_decode=True, encoding='utf-8', auto_content_length=True, recv_bytes=1024)

  Bases: `stomp.connect.BaseConnection`, `stomp.protocol.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, use_ssl=False, ssl_key_file=None, ssl_cert_file=None, ssl_ca_certs=None, ssl_cert_validator=None, ssl_version=<_SSLMethod.PROTOCOL_TLSv1: 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, recv_byte=1024)

  Bases: `stomp.connect.BaseConnection`, `stomp.protocol.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

      - 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, use_ssl=False, ssl_key_file=None, ssl_cert_file=None, ssl_ca_certs=None, ssl_cert_validator=None, ssl_version=<_SSLMethod.PROTOCOL_TLSv1: 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, recv_bytes=1024)

  Bases: `stomp.connect.BaseConnection`, `stomp.protocol.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

      - 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

  `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: `stomp.exception.StompException`

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

exception `stomp.exception.``ConnectionClosedException`

  Bases: `stomp.exception.StompException`

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

exception `stomp.exception.``InterruptedException`

  Bases: `stomp.exception.StompException`

  Raised by receive when data read is interrupted.

exception `stomp.exception.``NotConnectedException`

  Bases: `stomp.exception.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

      - headers (dict) – the message headers

      - body – the message body

  `on_connected`(frame)

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

    Parameters

      - headers (dict) – a dictionary containing all headers sent by the server as key/value pairs.

      - body – the frame’s payload. This is usually empty for CONNECTED frames.

  `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_error`(frame)

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

    Parameters

      - headers (dict) – a dictionary containing all headers sent by the server as key/value pairs.

      - body – the frame’s payload - usually a detailed error description.

  `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

      - headers (dict) – a dictionary containing all headers sent by the server as key/value pairs.

      - body – the frame’s payload - the message body.

  `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

      - headers (dict) – a dictionary containing all headers sent by the server as key/value pairs.

      - body – the frame’s payload. This is usually empty for RECEIPT frames.

  `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 frame to be sent

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

  Bases: `stomp.listener.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

      - headers (dict) – headers in the connection message

      - body – the message body

  `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`(*_)

    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

      - headers (dict) – headers in the message

      - body – the message content

  `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: `stomp.listener.ConnectionListener`

  `on_before_message`(frame)
    Parameters

      - headers (dict) –

      - body –

  `on_connected`(frame)
    Parameters

      - headers (dict) –

      - body –

  `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

      - headers (dict) –

      - body –

  `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

      - headers (dict) –

      - body –

  `on_receipt`(frame)
    Parameters

      - headers (dict) –

      - body –

  `on_send`(frame)
    Parameters

      frame (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: `stomp.listener.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

      - headers (dict) – headers in the message

      - body – the message content

  `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

      - headers (dict) – headers in the message

      - body – the message content

  `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: `stomp.listener.StatsListener`, `stomp.listener.WaitingListener`, `stomp.listener.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

      - headers (dict) – the message headers

      - body – the message body

  `on_connected`(frame)

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

    Parameters

      - headers (dict) – a dictionary containing all headers sent by the server as key/value pairs.

      - body – the frame’s payload. This is usually empty for CONNECTED frames.

  `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

      - headers (dict) – headers in the message

      - body – the message content

  `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

      - headers (dict) –

      - message –

  `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

      - headers (dict) – a dictionary containing all headers sent by the server as key/value pairs.

      - body – the frame’s payload. This is usually empty for RECEIPT frames.

  `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: `stomp.listener.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

      - headers (dict) – headers in the message

      - body – the message content

  `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: `stomp.listener.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: `stomp.listener.HeartbeatListener`, `stomp.listener.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

    - heart_beat_receive_scale (float) – 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, **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

  `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)

      - body – the content of the message

      - content_type (str) – the MIME type of message

      - headers (dict) – additional headers to send in the message frame

      - 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)

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

      - 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: `stomp.protocol.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

    - heart_beat_receive_scale (float) – 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, **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

      - 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: `stomp.listener.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

      - headers (dict) – the map of headers associated with the message

      - body – the content of the message

  `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, use_ssl=False, ssl_key_file=None, ssl_cert_file=None, ssl_ca_certs=None, ssl_cert_validator=None, ssl_version=None, timeout=None, keepalive=None, vhost=None, auto_decode=True, encoding='utf-8', recv_bytes=1024, is_eol_fc=<function is_eol_default>)

  Bases: `stomp.transport.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)

    - use_ssl (bool) – deprecated, see `set_ssl()`

    - ssl_cert_file – deprecated, see `set_ssl()`

    - ssl_key_file – deprecated, see `set_ssl()`

    - ssl_ca_certs – deprecated, see `set_ssl()`

    - ssl_cert_validator – deprecated, see `set_ssl()`

    - ssl_version – deprecated, see `set_ssl()`

    - 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

    - 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_TLSv1: 3>, 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

## 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

  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

  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