0
# uAMQP
1

2
An AMQP 1.0 client library for Python that provides comprehensive messaging capabilities for building applications using the Advanced Message Queuing Protocol. It offers both synchronous and asynchronous APIs for sending and receiving messages, supports various authentication methods, and provides extensive configuration options for connections, sessions, and message handling.
3

4
## Package Information
5

6
- **Package Name**: uamqp
7
- **Language**: Python  
8
- **Installation**: `pip install uamqp`
9
- **Python Support**: Python 3.6+
10

11
## Core Imports
12

13
```python
14
import uamqp
15
```
16

17
Common imports for basic messaging:
18

19
```python
20
from uamqp import send_message, receive_message, receive_messages
21
from uamqp import Message, Source, Target
22
from uamqp import SendClient, ReceiveClient
23
```
24

25
Authentication imports:
26

27
```python
28
from uamqp.authentication import SASLPlain, SASLAnonymous, SASTokenAuth
29
```
30

31
## Basic Usage
32

33
```python
34
import uamqp
35
from uamqp.authentication import SASLPlain
36

37
# Send a single message
38
target = "amqps://example.com/queue"
39
message = "Hello, AMQP!"
40
auth = SASLPlain("username", "password")
41

42
uamqp.send_message(target, message, auth=auth)
43

44
# Receive messages
45
source = "amqps://example.com/queue"
46
messages = uamqp.receive_messages(source, auth=auth, max_batch_size=10)
47

48
for message in messages:
49
    print(message.get_data())
50
    message.accept()
51
```
52

53
## Architecture
54

55
The uAMQP library follows the AMQP 1.0 protocol architecture:
56

57
- **Connection**: Manages the network connection to the AMQP broker
58
- **Session**: Provides a logical grouping of links within a connection
59
- **Links**: Unidirectional pathways for message transfer (MessageSender/MessageReceiver)
60
- **Message**: The core unit of data transfer with properties, headers, and body
61
- **Authentication**: Various authentication mechanisms (SASL, CBS tokens)
62

63
The library provides both high-level client APIs (SendClient, ReceiveClient) for ease of use and low-level protocol access for advanced scenarios.
64

65
## Capabilities
66

67
### High-Level Messaging API
68

69
Simple functions for common messaging operations including sending single messages, receiving single messages, and batch message operations.
70

71
```python { .api }
72
def send_message(target, data, auth=None, debug=False):
73
    """Send a single message to AMQP endpoint."""
74

75
def receive_message(source, auth=None, timeout=0, debug=False):
76
    """Receive a single message from an AMQP endpoint."""
77

78
def receive_messages(source, auth=None, max_batch_size=None, timeout=0, debug=False, **kwargs):
79
    """Receive a batch of messages from an AMQP endpoint."""
80

81
def get_platform_info():
82
    """
83
    Get current platform information.
84
    
85
    Returns:
86
        str: Platform information string
87
    """
88
```
89

90
[High-Level Messaging](./high-level-messaging.md)
91

92
### Message Management
93

94
Core message classes for creating, manipulating, and processing AMQP messages including support for different body types, properties, and batch operations.
95

96
```python { .api }
97
class Message:
98
    def __init__(self, body=None, properties=None, application_properties=None, 
99
                 annotations=None, header=None, msg_format=None, encoding='UTF-8', 
100
                 body_type=None, footer=None, delivery_annotations=None): ...
101

102
class BatchMessage:
103
    def __init__(self, data=None, properties=None, application_properties=None,
104
                 annotations=None, header=None, multi_messages=False, encoding='UTF-8'): ...
105
```
106

107
[Message Management](./message-management.md)
108

109
### Client APIs
110

111
High-level client classes for sending and receiving messages with built-in connection management, error handling, and batching capabilities.
112

113
```python { .api }
114
class SendClient:
115
    def __init__(self, target, auth=None, client_name=None, debug=False, **kwargs): ...
116

117
class ReceiveClient:
118
    def __init__(self, source, auth=None, client_name=None, debug=False, **kwargs): ...
119
```
120

121
[Client APIs](./client-apis.md)
122

123
### Authentication
124

125
Comprehensive authentication support including SASL mechanisms, token-based authentication, and Claims-Based Security (CBS) for Azure services.
126

127
```python { .api }
128
class SASLPlain:
129
    def __init__(self, hostname, username, password, port=5671, **kwargs): ...
130

131
class SASTokenAuth:
132
    def __init__(self, hostname, port, token, token_type="servicebus.windows.net:sastoken", **kwargs): ...
133
```
134

135
[Authentication](./authentication.md)
136

137
### Connection and Session Management
138

139
Low-level AMQP protocol management including connection establishment, session management, and link creation for advanced messaging scenarios.
140

141
```python { .api }
142
class Connection:
143
    def __init__(self, hostname, sasl=None, container_id=None, max_frame_size=None, **kwargs): ...
144

145
class Session:
146
    def __init__(self, connection, incoming_window=None, outgoing_window=None, handle_max=None): ...
147
```
148

149
[Connection and Session Management](./connection-session.md)
150

151
### Address and Endpoints
152

153
AMQP endpoint addressing including source and target configuration with support for filters, dynamic addresses, and link properties.
154

155
```python { .api }
156
class Source:
157
    def __init__(self, address=None, **kwargs): ...
158

159
class Target:
160
    def __init__(self, address=None, **kwargs): ...
161
```
162

163
[Address and Endpoints](./address-endpoints.md)
164

165
### Low-Level Protocol Access
166

167
Direct access to AMQP protocol elements including message senders, receivers, and protocol-level message handling for advanced use cases.
168

169
```python { .api }
170
class MessageSender:
171
    def __init__(self, session, source, target, name=None, **kwargs): ...
172

173
class MessageReceiver:
174
    def __init__(self, session, source, target, name=None, **kwargs): ...
175
```
176

177
[Low-Level Protocol Access](./low-level-protocol.md)
178

179
### AMQP Types and Constants
180

181
Type system for AMQP values and comprehensive constants for protocol states, error codes, and configuration options.
182

183
```python { .api }
184
class AMQPType:
185
    def __init__(self, value): ...
186

187
class MessageState:
188
    WaitingToBeSent = 0
189
    WaitingForSendAck = 1
190
    SendComplete = 2
191
    # ...
192
```
193

194
[AMQP Types and Constants](./types-constants.md)
195

196
### Error Handling
197

198
Comprehensive error handling with custom exceptions, error policies, and retry mechanisms for robust messaging applications.
199

200
```python { .api }
201
class ErrorPolicy:
202
    def __init__(self, max_retries=3, on_error=None): ...
203

204
class AMQPError(Exception): ...
205
class AMQPConnectionError(AMQPError): ...
206
```
207

208
[Error Handling](./error-handling.md)
209

210
### Async Operations
211

212
Asynchronous AMQP operations for Python 3.4+ with async/await support for high-performance messaging applications.
213

214
```python { .api }
215
class SendClientAsync:
216
    def __init__(self, target, auth=None, client_name=None, debug=False, **kwargs): ...
217

218
class ReceiveClientAsync:
219
    def __init__(self, source, auth=None, client_name=None, debug=False, **kwargs): ...
220
```
221

222
[Async Operations](./async-operations.md)