0
# stomp.py
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: stomp.py
7
- **Language**: Python
8
- **Installation**: `pip install stomp.py`
9
- **Version**: 8.2.0
10

11
## Core Imports
12

13
```python
14
import stomp
15
```
16

17
Main connection classes:
18

19
```python
20
from stomp import Connection, Connection10, Connection11, Connection12
21
from stomp import ConnectionListener, StatsListener, WaitingListener
22
```
23

24
Protocol-specific imports:
25

26
```python
27
# STOMP 1.0
28
from stomp import Connection10
29

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

33
# STOMP 1.2
34
from stomp import Connection12
35

36
# WebSocket
37
from stomp import WSConnection
38
```
39

40
## Basic Usage
41

42
```python
43
import stomp
44
import time
45

46
# Create connection listener to handle events
47
class MyListener(stomp.ConnectionListener):
48
    def on_error(self, frame):
49
        print(f'Received error: {frame.body}')
50
    
51
    def on_message(self, frame):
52
        print(f'Received message: {frame.body}')
53

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

57
# Set listener
58
conn.set_listener('', MyListener())
59

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

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

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

69
# Wait for messages
70
time.sleep(5)
71

72
# Disconnect
73
conn.disconnect()
74
```
75

76
## Architecture
77

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

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

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

88
## Capabilities
89

90
### Connection Management
91

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

94
```python { .api }
95
class Connection:
96
    def __init__(self, host_and_ports=None, heartbeats=(0, 0), **kwargs): ...
97
    def connect(self, username=None, passcode=None, wait=False, headers=None, **keyword_headers): ...
98
    def disconnect(self, receipt=None, headers=None, **keyword_headers): ...
99
    def is_connected(self) -> bool: ...
100
```
101

102
[Connection Management](./connections.md)
103

104
### Event Handling
105

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

108
```python { .api }
109
class ConnectionListener:
110
    def on_connecting(self, host_and_port): ...
111
    def on_connected(self, frame): ...
112
    def on_message(self, frame): ...
113
    def on_error(self, frame): ...
114
    def on_disconnected(self): ...
115
```
116

117
[Event Handling](./listeners.md)
118

119
### WebSocket Support
120

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

123
```python { .api }
124
class WSConnection:
125
    def __init__(self, url, heartbeats=(0, 0), **kwargs): ...
126
    def connect(self, username=None, passcode=None, wait=False, headers=None, **keyword_headers): ...
127
```
128

129
[WebSocket Support](./websocket.md)
130

131
### Protocol Operations
132

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

135
```python { .api }
136
def send(self, body='', destination=None, headers=None, **keyword_headers): ...
137
def subscribe(self, destination, id=None, ack='auto', headers=None, **keyword_headers): ...
138
def unsubscribe(self, destination=None, id=None, headers=None, **keyword_headers): ...
139
def ack(self, id, subscription=None, transaction=None, headers=None, **keyword_headers): ...
140
```
141

142
[Protocol Operations](./protocol.md)
143

144
### Command-Line Interface
145

146
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.
147

148
```python { .api }
149
def main(): ...  # Launch interactive STOMP CLI client
150
class StompCLI(Cmd, ConnectionListener): ...  # Interactive command processor
151

152
# Key CLI commands:
153
def do_connect(self, args): ...  # Connect to broker
154
def do_send(self, args): ...     # Send messages
155
def do_subscribe(self, args): ...  # Subscribe to destinations
156
def do_begin(self, args): ...    # Begin transactions
157
```
158

159
[Command-Line Interface](./cli.md)
160

161
### Transport Adapters
162

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

165
```python { .api }
166
class MulticastConnection: ...  # STOMP over UDP multicast
167
class MulticastTransport: ...   # Multicast transport implementation
168

169
# Advanced transport configuration:
170
def override_threading(self, create_thread_fc): ...  # Custom threading
171
def wait_for_connection(self, timeout=None): ...     # Synchronous connection
172
def set_keepalive_options(self, keepalive_options): ...  # Advanced keepalive
173
```
174

175
[Transport Adapters](./adapters.md)
176

177
### Utilities and Helpers
178

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

181
```python { .api }
182
def convert_frame(frame): ...     # Frame processing
183
def parse_headers(lines, offset=0): ...  # Header parsing
184
def calculate_heartbeats(send_heartbeat, client_heartbeat): ...  # Heartbeat negotiation
185
class TestListener(StatsListener, WaitingListener, PrintingListener): ...  # Testing support
186
```
187

188
[Utilities and Helpers](./utilities.md)
189

190
### Error Handling and Logging
191

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

194
```python { .api }
195
class StompException(Exception): ...
196
class ConnectionClosedException(StompException): ...
197
class NotConnectedException(StompException): ...
198
class ConnectFailedException(StompException): ...
199
```
200

201
[Types and Exceptions](./types.md)