stomp package

Submodules

stomp.backward module

stomp.backward.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.backward2 module

Python2-specific versions of various functions used by stomp.py

stomp.backward2.decode(byte_data)

Decode the byte data to a string - in the case of this Py2 version, we can’t really do anything (Py3 differs).

Parameters:byte_data (bytes) –
Return type:str
stomp.backward2.encode(char_data)

Encode the parameter as a byte string.

Parameters:char_data –
Return type:bytes
stomp.backward2.input_prompt(prompt)

Get user input

Return type:str
stomp.backward2.join(chars=())

Join a sequence of characters into a string.

Parameters:chars (bytes) –
Rtype str:
stomp.backward2.pack(pieces=())

Join a sequence of strings together (note: py3 version differs)

Parameters:pieces (list) –
Return type:bytes

stomp.backward3 module

Python3-specific versions of various functions used by stomp.py

stomp.backward3.decode(byte_data)

Decode the byte data to a string if not None.

Parameters:byte_data (bytes) – the data to decode
Return type:str
stomp.backward3.encode(char_data)

Encode the parameter as a byte string.

Parameters:char_data – the data to encode
Return type:bytes
stomp.backward3.input_prompt(prompt)

Get user input

Parameters:prompt (str) – the prompt to display to the user
Return type:str
stomp.backward3.join(chars=())

Join a sequence of characters into a string.

Parameters:chars (bytes) – list of chars
Return type:str
stomp.backward3.pack(pieces=())

Join a sequence of strings together.

Parameters:pieces (list) – list of strings
Return type:bytes

stomp.backwardsock module

Networking functions to support backwards compatibility.

Distinct from the backward(2/3) functions to handle ipv6 changes between Python versions 2.5 and 2.6.

stomp.backwardsock25 module

Python2.5 (and lower) specific versions of various networking (ipv6) functions used by stomp.py

stomp.backwardsock25.get_socket(host, port, timeout=None)

Return a socket.

Parameters:
  • host (str) – the hostname to connect to
  • port (int) – the port number to connect to
  • timeout – if specified, set the socket timeout

stomp.backwardsock26 module

Python2.6 (and greater) specific versions of various networking (ipv6) functions used by stomp.py

stomp.backwardsock26.get_socket(host, port, timeout=None)

Return a socket connection.

Parameters:
  • host (str) – the hostname to connect to
  • port (int) – the port number to connect to
  • timeout – if specified, set the socket timeout

stomp.colors module

Color ‘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(*args, **kwargs)
is_connected()
Return type:bool
remove_listener(name)
Parameters:name (str) –
set_listener(name, lstnr)
Parameters:
set_receipt(receipt_id, value)
set_ssl(*args, **kwargs)
start()
stop()
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, wait_on_receipt=False, ssl_version=3, timeout=None, keepalive=None, auto_decode=True, auto_content_length=True)

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.

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, wait_on_receipt=False, ssl_version=3, timeout=None, heartbeats=(0, 0), keepalive=None, vhost=None, auto_decode=True, auto_content_length=True)

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.

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, wait_on_receipt=False, ssl_version=3, timeout=None, heartbeats=(0, 0), keepalive=None, vhost=None, auto_decode=True, auto_content_length=True)

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.

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

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: exceptions.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(headers, body)

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(headers, body)

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(headers, body)

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(headers, body)

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(headers, body)

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_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(heartbeats)

Bases: stomp.listener.ConnectionListener

Listener used to handle STOMP heartbeating.

on_connected(headers, body)

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()
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(headers, body)

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

Bases: stomp.listener.ConnectionListener

on_before_message(headers, body)
Parameters:
  • headers (dict) –
  • body –
on_connected(headers, body)
Parameters:
  • headers (dict) –
  • body –
on_connecting(host_and_port)
Parameters:host_and_port ((str,int)) –
on_disconnected()
on_error(headers, body)
Parameters:
  • headers (dict) –
  • body –
on_heartbeat()
on_heartbeat_timeout()
on_message(headers, body)
Parameters:
  • headers (dict) –
  • body –
on_receipt(headers, body)
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(headers, body)

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(headers, body)

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)

Bases: stomp.listener.StatsListener, stomp.listener.WaitingListener

Implementation of StatsListener and WaitingListener. Useful for testing.

get_latest_message()
on_heartbeat()
on_message(headers, message)
Parameters:
  • headers (dict) –
  • message –
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_receipt(headers, body)

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

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

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

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

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

stomp.transport module

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

class stomp.transport.BaseTransport(wait_on_receipt=False, auto_decode=True)

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:
  • wait_on_receipt (bool) – deprecated, ignored
  • 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)
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, headers=None, body=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.

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, wait_on_receipt=False, ssl_version=None, timeout=None, keepalive=None, vhost=None, auto_decode=True)

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
  • 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
  • wait_on_receipt (bool) – deprecated, ignored
  • 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
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=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 – 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=None, 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.convert_frame_to_lines(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.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.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.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.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