# stomp package

## Subpackages

- stomp.adapter package
  - Submodules
  - stomp.adapter.multicast module
  - Module contents

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

    - name (str) –
    - lstnr (ConnectionListener) –

  `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=<_SSLMethod.PROTOCOL_TLSv1: 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=<_SSLMethod.PROTOCOL_TLSv1: 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=<_SSLMethod.PROTOCOL_TLSv1: 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: `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=<_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 – 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