or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

adapters.mdcli.mdconnections.mdindex.mdlisteners.mdprotocol.mdtypes.mdutilities.mdwebsocket.md
tile.json

tessl/pypi-stomp-py

Python STOMP client library supporting versions 1.0, 1.1 and 1.2 of the protocol

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/stomp.py@8.2.x

To install, run

npx @tessl/cli install tessl/pypi-stomp-py@8.2.0

index.mddocs/

stomp.py

A comprehensive Python client library for the STOMP (Simple Text Oriented Messaging Protocol) that supports versions 1.0, 1.1, and 1.2 of the protocol. The library enables Python applications to connect to message brokers like ActiveMQ, Artemis, and RabbitMQ for reliable asynchronous messaging.

Package Information

  • Package Name: stomp.py
  • Language: Python
  • Installation: pip install stomp.py
  • Version: 8.2.0

Core Imports

import stomp

Main connection classes:

from stomp import Connection, Connection10, Connection11, Connection12
from stomp import ConnectionListener, StatsListener, WaitingListener

Protocol-specific imports:

# STOMP 1.0
from stomp import Connection10

# STOMP 1.1 (default)
from stomp import Connection, Connection11

# STOMP 1.2
from stomp import Connection12

# WebSocket
from stomp import WSConnection

Basic Usage

import stomp
import time

# Create connection listener to handle events
class MyListener(stomp.ConnectionListener):
    def on_error(self, frame):
        print(f'Received error: {frame.body}')
    
    def on_message(self, frame):
        print(f'Received message: {frame.body}')

# Create connection (defaults to STOMP 1.1)
conn = stomp.Connection([('localhost', 61613)])

# Set listener
conn.set_listener('', MyListener())

# Connect to broker
conn.connect('admin', 'password', wait=True)

# Send a message
conn.send(body='Hello STOMP!', destination='/queue/test')

# Subscribe to a queue
conn.subscribe(destination='/queue/test', id=1, ack='auto')

# Wait for messages
time.sleep(5)

# Disconnect
conn.disconnect()

Architecture

The stomp.py library follows a layered architecture designed for flexibility and protocol compliance:

  • Connection Layer: Protocol-specific connection classes (Connection10, Connection11, Connection12) that handle STOMP communication
  • Transport Layer: Low-level TCP socket management with SSL support, connection pooling, and automatic reconnection
  • Protocol Layer: STOMP frame processing, command handling, and version-specific protocol compliance
  • Listener Pattern: Event-driven architecture using listener callbacks for connection events, messages, errors, and receipts
  • Adapter Layer: WebSocket and multicast adapters for specialized transport mechanisms

This design enables the library to support multiple STOMP versions simultaneously while providing a consistent API across different message brokers and transport mechanisms.

Capabilities

Connection Management

Comprehensive connection classes supporting all STOMP protocol versions with automatic reconnection, SSL/TLS support, heartbeat handling, and connection pooling for robust message broker connectivity.

class Connection:
    def __init__(self, host_and_ports=None, heartbeats=(0, 0), **kwargs): ...
    def connect(self, username=None, passcode=None, wait=False, headers=None, **keyword_headers): ...
    def disconnect(self, receipt=None, headers=None, **keyword_headers): ...
    def is_connected(self) -> bool: ...

Connection Management

Event Handling

Listener-based event system for handling connection events, message delivery, error conditions, and protocol-specific events with built-in listeners for common use cases.

class ConnectionListener:
    def on_connecting(self, host_and_port): ...
    def on_connected(self, frame): ...
    def on_message(self, frame): ...
    def on_error(self, frame): ...
    def on_disconnected(self): ...

Event Handling

WebSocket Support

WebSocket transport adapter enabling STOMP messaging over WebSocket connections for browser-based applications and web-friendly messaging patterns.

class WSConnection:
    def __init__(self, url, heartbeats=(0, 0), **kwargs): ...
    def connect(self, username=None, passcode=None, wait=False, headers=None, **keyword_headers): ...

WebSocket Support

Protocol Operations

Core STOMP protocol operations including message sending, queue subscription, transaction management, and acknowledgment handling across all supported protocol versions.

def send(self, body='', destination=None, headers=None, **keyword_headers): ...
def subscribe(self, destination, id=None, ack='auto', headers=None, **keyword_headers): ...
def unsubscribe(self, destination=None, id=None, headers=None, **keyword_headers): ...
def ack(self, id, subscription=None, transaction=None, headers=None, **keyword_headers): ...

Protocol Operations

Command-Line Interface

Interactive and batch STOMP client providing comprehensive command-line access to all stomp.py functionality including message sending, subscription management, transaction handling, and broker connectivity testing.

def main(): ...  # Launch interactive STOMP CLI client
class StompCLI(Cmd, ConnectionListener): ...  # Interactive command processor

# Key CLI commands:
def do_connect(self, args): ...  # Connect to broker
def do_send(self, args): ...     # Send messages
def do_subscribe(self, args): ...  # Subscribe to destinations
def do_begin(self, args): ...    # Begin transactions

Command-Line Interface

Transport Adapters

Specialized transport adapters extending stomp.py beyond traditional TCP connections to support multicast, broadcast messaging, and alternative transport mechanisms for specific deployment scenarios.

class MulticastConnection: ...  # STOMP over UDP multicast
class MulticastTransport: ...   # Multicast transport implementation

# Advanced transport configuration:
def override_threading(self, create_thread_fc): ...  # Custom threading
def wait_for_connection(self, timeout=None): ...     # Synchronous connection
def set_keepalive_options(self, keepalive_options): ...  # Advanced keepalive

Transport Adapters

Utilities and Helpers

Core utility functions, constants, logging configuration, and helper methods that support stomp.py's internal operations and provide convenient functionality for advanced use cases.

def convert_frame(frame): ...     # Frame processing
def parse_headers(lines, offset=0): ...  # Header parsing
def calculate_heartbeats(send_heartbeat, client_heartbeat): ...  # Heartbeat negotiation
class TestListener(StatsListener, WaitingListener, PrintingListener): ...  # Testing support

Utilities and Helpers

Error Handling and Logging

Comprehensive exception hierarchy and configurable logging system for debugging connection issues, protocol errors, and message delivery problems.

class StompException(Exception): ...
class ConnectionClosedException(StompException): ...
class NotConnectedException(StompException): ...
class ConnectFailedException(StompException): ...

Types and Exceptions