stomp package

Subpackages

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