stomp-py

8.2.0 · active · verified Sat Apr 11

stomp.py is a Python client library for accessing messaging servers such as ActiveMQ, ActiveMQ Artemis, or RabbitMQ using the STOMP protocol (versions 1.0, 1.1, and 1.2). It provides both programmatic access and a command-line client for testing. The library, currently at version 8.2.0, adheres to semantic versioning and exclusively supports Python 3.x, having ended Python 2.x support in January 2020.

Warnings

breaking stomp.py officially ended support for Python 2.x as of January 2020. All versions 4.2+ are Python 3.x only. Attempting to use newer versions with Python 2.x will result in compatibility errors.
Fix: Migrate your application to Python 3.7+ (current minimum requirement for stomp.py).
breaking In version 8.2.0, the `stomp.__version__` attribute changed from a tuple to a string. Tools or scripts that parsed `stomp.__version__` as a tuple for version checks will break.
Fix: Update any version parsing logic to expect a string, or use `stomp.get_version()` which returns a tuple, if available in the specific version being used.
gotcha When configuring SSL, `conn.set_ssl()` must be called *before* `conn.start()`. Additionally, use `ssl.PROTOCOL_TLS` instead of deprecated version-specific protocols like `ssl.PROTOCOL_TLSv1_2` for broader compatibility.
Fix: Ensure `set_ssl` is invoked after connection object creation but before starting the connection. Use `ssl.PROTOCOL_TLS` for SSL version parameter.
gotcha By default, `stomp.Connection()` might negotiate STOMP 1.1. If you explicitly require STOMP 1.2 features, it's recommended to use `stomp.Connection12()` or specify `headers={'accept-version': '1.2'}` in `conn.connect()` to ensure the correct protocol version is used.
Fix: Use `stomp.Connection12()` or pass `headers={'accept-version': '1.2'}` to `conn.connect()`.
gotcha Persistent disconnections or connection failures can be caused by aggressive reconnection strategies or heartbeat timeouts. The default reconnection attempts (1 per second for 30 seconds) might be too short for some brokers.
Fix: Configure reconnection parameters like `reconnect_sleep_initial`, `reconnect_sleep_increase`, `reconnect_sleep_jitter` on the `stomp.Connection` object for a more robust exponential back-off strategy. Also, ensure appropriate heartbeat values (`heart-beat` header in `connect`) are set and handled correctly by both client and server.
deprecated Older versions (prior to v2, circa 2013) of stomp.py were distributed as a single Python file (`stomp.py`). Modern versions are installed as a module. Direct imports of `stomp.py` as a file will fail.
Fix: Ensure you `pip install stomp-py` and `import stomp`. Do not attempt to use or import the old single-file distribution.

Install

pip install stomp-py Install latest version

Imports

Connection
```
import stomp
conn = stomp.Connection()
```
While Connection is in stomp.connect, the common and recommended import is directly from the top-level 'stomp' module for convenience.
ConnectionListener
```
import stomp
class MyListener(stomp.ConnectionListener): ...
```
Similar to Connection, ConnectionListener is commonly imported via the top-level 'stomp' module.

Quickstart

This quickstart demonstrates how to establish a connection to a STOMP broker, register a listener to handle incoming messages, subscribe to a destination, send a message, and then disconnect. It uses environment variables for host, port, username, password, and destination, falling back to common defaults. It also explicitly sets STOMP protocol version 1.2 and heartbeats during connection.

import os
import time
import stomp

class MyListener(stomp.ConnectionListener):
    def on_error(self, headers, body):
        print(f'ERROR: {body}')

    def on_message(self, headers, body):
        print(f'MESSAGE: {body}')

host = os.environ.get('STOMP_HOST', 'localhost')
port = int(os.environ.get('STOMP_PORT', '61613'))
username = os.environ.get('STOMP_USERNAME', 'guest')
password = os.environ.get('STOMP_PASSWORD', 'guest')
destination = os.environ.get('STOMP_DESTINATION', '/queue/test')

host_and_ports = [(host, port)]

try:
    conn = stomp.Connection(host_and_ports)
    conn.set_listener(MyListener())
    conn.connect(username, password, wait=True, headers={'accept-version': '1.2', 'heart-beat': '10000,10000'})
    print(f"Connected to {host}:{port}")

    conn.subscribe(destination=destination, id=1, ack='auto')
    print(f"Subscribed to {destination}")

    print(f"Sending message to {destination}")
    conn.send(body='Hello, STOMP!', destination=destination)

    time.sleep(2) # Give time for message to be received

    conn.disconnect()
    print("Disconnected.")
except stomp.exception.ConnectFailedException as e:
    print(f"Failed to connect: {e}")
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →