0
# Constants and Enums
1

2
Enumeration values and constants for configuring Service Bus behavior including receive modes, message states, transport types, and entity sub-queues.
3

4
## Capabilities
5

6
### Receive Modes
7

8
Configure how messages are received from queues and subscriptions.
9

10
```python { .api }
11
class ServiceBusReceiveMode(str, Enum):
12
    """
13
    Message receive modes for controlling message acknowledgment behavior.
14
    """
15
    PEEK_LOCK = "peeklock"
16
    """
17
    Messages are locked for processing and must be explicitly completed, abandoned, 
18
    deferred, or dead-lettered. Provides at-least-once delivery guarantee.
19
    """
20
    
21
    RECEIVE_AND_DELETE = "receiveanddelete"
22
    """
23
    Messages are automatically deleted when received. Provides at-most-once 
24
    delivery with potential message loss if processing fails.
25
    """
26
```
27

28
#### Usage Example
29

30
```python
31
from azure.servicebus import ServiceBusClient, ServiceBusReceiveMode
32

33
client = ServiceBusClient.from_connection_string("your_connection_string")
34

35
# Peek-lock mode (default) - messages must be explicitly completed
36
with client.get_queue_receiver("my-queue", receive_mode=ServiceBusReceiveMode.PEEK_LOCK) as receiver:
37
    messages = receiver.receive_messages(max_message_count=5)
38
    for message in messages:
39
        try:
40
            process_message(message)
41
            receiver.complete_message(message)  # Must explicitly complete
42
        except Exception:
43
            receiver.abandon_message(message)   # Or abandon for retry
44

45
# Receive-and-delete mode - messages are automatically removed
46
with client.get_queue_receiver("my-queue", receive_mode=ServiceBusReceiveMode.RECEIVE_AND_DELETE) as receiver:
47
    messages = receiver.receive_messages(max_message_count=5)
48
    for message in messages:
49
        # Message is already deleted from queue - no settlement needed
50
        process_message(message)
51
```
52

53
### Message States
54

55
Indicate the current state of messages in the Service Bus.
56

57
```python { .api }
58
class ServiceBusMessageState(int, Enum):
59
    """
60
    States that a message can be in within Service Bus.
61
    """
62
    ACTIVE = 0
63
    """
64
    Message is active and available for processing in the queue or subscription.
65
    """
66
    
67
    DEFERRED = 1
68
    """
69
    Message has been deferred for later processing and must be retrieved 
70
    using its sequence number.
71
    """
72
    
73
    SCHEDULED = 2
74
    """
75
    Message is scheduled for delivery at a future time and is not yet 
76
    available for processing.
77
    """
78
```
79

80
#### Usage Example
81

82
```python
83
from azure.servicebus import ServiceBusClient, ServiceBusMessageState
84

85
client = ServiceBusClient.from_connection_string("your_connection_string")
86

87
with client.get_queue_receiver("my-queue") as receiver:
88
    messages = receiver.receive_messages(max_message_count=10)
89
    
90
    for message in messages:
91
        print(f"Message: {message.body}")
92
        print(f"State: {message.state}")
93
        
94
        if message.state == ServiceBusMessageState.ACTIVE:
95
            print("Message is active and ready for processing")
96
            receiver.complete_message(message)
97
            
98
        elif message.state == ServiceBusMessageState.DEFERRED:
99
            print("Message was previously deferred")
100
            # Handle deferred message processing
101
            
102
        elif message.state == ServiceBusMessageState.SCHEDULED:
103
            print("Message is scheduled for future delivery")
104
            # This shouldn't typically appear in received messages
105
```
106

107
### Sub-Queue Types
108

109
Specify sub-queues for accessing dead letter and transfer dead letter messages.
110

111
```python { .api }
112
class ServiceBusSubQueue(str, Enum):
113
    """
114
    Sub-queue types for accessing special message queues.
115
    """
116
    DEAD_LETTER = "deadletter"
117
    """
118
    Dead letter sub-queue containing messages that could not be processed 
119
    successfully and have exceeded the maximum delivery count or expired.
120
    """
121
    
122
    TRANSFER_DEAD_LETTER = "transferdeadletter"
123
    """
124
    Transfer dead letter sub-queue containing messages that could not be 
125
    forwarded to their destination due to forwarding failures.
126
    """
127
```
128

129
#### Usage Example
130

131
```python
132
from azure.servicebus import ServiceBusClient, ServiceBusSubQueue
133

134
client = ServiceBusClient.from_connection_string("your_connection_string")
135

136
# Access dead letter messages from a queue
137
with client.get_queue_receiver("my-queue", sub_queue=ServiceBusSubQueue.DEAD_LETTER) as dlq_receiver:
138
    dead_messages = dlq_receiver.receive_messages(max_message_count=10)
139
    
140
    for message in dead_messages:
141
        print(f"Dead letter message: {message.body}")
142
        print(f"Dead letter reason: {message.dead_letter_reason}")
143
        print(f"Dead letter error: {message.dead_letter_error_description}")
144
        print(f"Delivery count: {message.delivery_count}")
145
        
146
        # Process dead letter message or resubmit to main queue
147
        if should_reprocess(message):
148
            resubmit_to_main_queue(message)
149
        
150
        dlq_receiver.complete_message(message)
151

152
# Access transfer dead letter messages
153
with client.get_queue_receiver("my-queue", sub_queue=ServiceBusSubQueue.TRANSFER_DEAD_LETTER) as tdlq_receiver:
154
    transfer_dead_messages = tdlq_receiver.receive_messages(max_message_count=5)
155
    
156
    for message in transfer_dead_messages:
157
        print(f"Transfer failed message: {message.body}")
158
        print(f"Original destination: {message.to}")
159
        # Handle transfer failures
160
        tdlq_receiver.complete_message(message)
161
```
162

163
### Session Filtering
164

165
Constants for session-based message processing.
166

167
```python { .api }
168
class ServiceBusSessionFilter(Enum):
169
    """
170
    Filter options for session selection.
171
    """
172
    NEXT_AVAILABLE = 0
173
    """
174
    Select the next available session that has messages waiting.
175
    """
176

177
# Convenience constant
178
NEXT_AVAILABLE_SESSION: ServiceBusSessionFilter = ServiceBusSessionFilter.NEXT_AVAILABLE
179
```
180

181
#### Usage Example
182

183
```python
184
from azure.servicebus import ServiceBusClient, NEXT_AVAILABLE_SESSION
185

186
client = ServiceBusClient.from_connection_string("your_connection_string")
187

188
# Connect to next available session
189
with client.get_queue_receiver("my-session-queue", session_id=NEXT_AVAILABLE_SESSION) as receiver:
190
    if receiver.session:
191
        print(f"Connected to session: {receiver.session.session_id}")
192
        
193
        messages = receiver.receive_messages(max_message_count=10)
194
        for message in messages:
195
            print(f"Session message: {message.body}")
196
            receiver.complete_message(message)
197
    else:
198
        print("No available sessions with messages")
199

200
# You can also connect to a specific session by ID
201
with client.get_queue_receiver("my-session-queue", session_id="specific-session-123") as receiver:
202
    # Process messages from this specific session
203
    pass
204
```
205

206
### Transport Types
207

208
Configure the underlying transport protocol for Service Bus connections.
209

210
```python { .api }
211
class TransportType(Enum):
212
    """
213
    Transport protocol options for Service Bus connections.
214
    """
215
    Amqp = "Amqp"
216
    """
217
    Standard AMQP 1.0 protocol over TCP. Provides the best performance 
218
    and feature support.
219
    """
220
    
221
    AmqpOverWebsocket = "AmqpOverWebsocket"
222
    """
223
    AMQP 1.0 protocol over WebSocket. Useful in environments with 
224
    firewall restrictions that block standard AMQP ports.
225
    """
226
```
227

228
#### Usage Example
229

230
```python
231
from azure.servicebus import ServiceBusClient, TransportType
232

233
# Use standard AMQP (default)
234
client = ServiceBusClient.from_connection_string(
235
    "your_connection_string",
236
    transport_type=TransportType.Amqp
237
)
238

239
# Use AMQP over WebSocket (for restrictive network environments)
240
client_websocket = ServiceBusClient.from_connection_string(
241
    "your_connection_string", 
242
    transport_type=TransportType.AmqpOverWebsocket
243
)
244

245
# Both clients work the same way
246
with client.get_queue_sender("my-queue") as sender:
247
    sender.send_messages(ServiceBusMessage("Hello via AMQP"))
248

249
with client_websocket.get_queue_sender("my-queue") as sender:
250
    sender.send_messages(ServiceBusMessage("Hello via WebSocket"))
251
```
252

253
### Management Entity Enums
254

255
Enumerations for entity properties in administrative operations.
256

257
```python { .api }
258
class EntityStatus(str, Enum):
259
    """
260
    Status values for Service Bus entities.
261
    """
262
    ACTIVE = "Active"
263
    """Entity is active and operational."""
264
    
265
    DISABLED = "Disabled"
266
    """Entity is disabled and not processing messages."""
267
    
268
    SEND_DISABLED = "SendDisabled"
269
    """Entity cannot receive new messages but can deliver existing ones."""
270
    
271
    RECEIVE_DISABLED = "ReceiveDisabled"
272
    """Entity cannot deliver messages but can receive new ones."""
273

274
class EntityAvailabilityStatus(str, Enum):
275
    """
276
    Availability status for Service Bus entities.
277
    """
278
    AVAILABLE = "Available"
279
    """Entity is available for operations."""
280
    
281
    LIMITED = "Limited"
282
    """Entity has limited availability."""
283
    
284
    RENAMING = "Renaming"
285
    """Entity is being renamed."""
286
    
287
    RESTORING = "Restoring"
288
    """Entity is being restored from backup."""
289
    
290
    UNKNOWN = "Unknown"
291
    """Entity availability status is unknown."""
292

293
class AccessRights(str, Enum):
294
    """
295
    Access rights for authorization rules.
296
    """
297
    MANAGE = "Manage"
298
    """Full management access including create, read, update, delete operations."""
299
    
300
    SEND = "Send"
301
    """Permission to send messages to the entity."""
302
    
303
    LISTEN = "Listen" 
304
    """Permission to receive messages from the entity."""
305

306
class MessagingSku(str, Enum):
307
    """
308
    Service Bus messaging tier/SKU options.
309
    """
310
    BASIC = "Basic"
311
    """Basic tier with limited features."""
312
    
313
    STANDARD = "Standard"
314
    """Standard tier with full feature set."""
315
    
316
    PREMIUM = "Premium"
317
    """Premium tier with enhanced performance and isolation."""
318

319
class NamespaceType(str, Enum):
320
    """
321
    Service Bus namespace types.
322
    """
323
    MESSAGING = "Messaging"
324
    """Standard messaging namespace."""
325
    
326
    NOTIFICATION_HUB = "NotificationHub"
327
    """Notification hub namespace."""
328
    
329
    MIXED = "Mixed"
330
    """Mixed namespace supporting multiple services."""
331
    
332
    EVENT_HUB = "EventHub"
333
    """Event hub namespace."""
334
    
335
    RELAY = "Relay"
336
    """Relay namespace."""
337
```
338

339
#### Usage Example
340

341
```python
342
from azure.servicebus.management import (
343
    ServiceBusAdministrationClient,
344
    EntityStatus,
345
    AccessRights,
346
    MessagingSku
347
)
348

349
admin_client = ServiceBusAdministrationClient.from_connection_string("your_connection_string")
350

351
# Create a queue with specific status
352
queue = admin_client.create_queue(
353
    "my-queue",
354
    status=EntityStatus.ACTIVE,
355
    max_delivery_count=5
356
)
357

358
# Check namespace information
359
namespace_info = admin_client.get_namespace_properties()
360
print(f"Namespace SKU: {namespace_info.messaging_sku}")
361

362
if namespace_info.messaging_sku == MessagingSku.PREMIUM:
363
    print("Using premium namespace with enhanced features")
364
elif namespace_info.messaging_sku == MessagingSku.STANDARD:
365
    print("Using standard namespace")
366

367
# Create authorization rule with specific rights
368
from azure.servicebus.management import AuthorizationRule
369

370
auth_rule = AuthorizationRule(
371
    key_name="MyAppRule",
372
    primary_key="generated_key",
373
    secondary_key="backup_key", 
374
    rights=[AccessRights.SEND, AccessRights.LISTEN]
375
)
376
```
377

378
### Message Count Details
379

380
Detailed breakdown of message counts in entities.
381

382
```python { .api }
383
class MessageCountDetails:
384
    """
385
    Detailed message count information for Service Bus entities.
386
    """
387
    @property
388
    def active_message_count(self) -> int:
389
        """Number of active messages."""
390
    
391
    @property
392
    def dead_letter_message_count(self) -> int:
393
        """Number of dead letter messages."""
394
    
395
    @property
396
    def scheduled_message_count(self) -> int:
397
        """Number of scheduled messages."""
398
    
399
    @property
400
    def transfer_dead_letter_message_count(self) -> int:
401
        """Number of transfer dead letter messages."""
402
    
403
    @property
404
    def transfer_message_count(self) -> int:
405
        """Number of messages being transferred."""
406
```
407

408
### API Version Constants
409

410
Available API versions for management operations.
411

412
```python { .api }
413
class ApiVersion(str, Enum):
414
    """
415
    Supported Service Bus management API versions.
416
    """
417
    V2017_04 = "2017-04"
418
    """API version from April 2017."""
419
    
420
    V2021_05 = "2021-05"
421
    """API version from May 2021 (default)."""
422

423
# Default API version used by the SDK
424
DEFAULT_VERSION: ApiVersion = ApiVersion.V2021_05
425
```
426

427
#### Usage Example
428

429
```python
430
from azure.servicebus.management import ServiceBusAdministrationClient, ApiVersion
431

432
# Use specific API version
433
admin_client = ServiceBusAdministrationClient.from_connection_string(
434
    "your_connection_string",
435
    api_version=ApiVersion.V2021_05
436
)
437

438
# Use default API version (recommended)
439
admin_client = ServiceBusAdministrationClient.from_connection_string(
440
    "your_connection_string"
441
)
442
```
443

444
## Import Patterns
445

446
Common import patterns for constants and enums.
447

448
```python
449
# Import specific enums
450
from azure.servicebus import (
451
    ServiceBusReceiveMode,
452
    ServiceBusMessageState,
453
    ServiceBusSubQueue,
454
    TransportType,
455
    NEXT_AVAILABLE_SESSION
456
)
457

458
# Import management enums
459
from azure.servicebus.management import (
460
    EntityStatus,
461
    EntityAvailabilityStatus,
462
    AccessRights,
463
    MessagingSku,
464
    NamespaceType,
465
    ApiVersion
466
)
467

468
# Use in client creation
469
client = ServiceBusClient.from_connection_string(
470
    "your_connection_string",
471
    transport_type=TransportType.AmqpOverWebsocket
472
)
473

474
# Use in receiver creation
475
receiver = client.get_queue_receiver(
476
    "my-queue",
477
    receive_mode=ServiceBusReceiveMode.PEEK_LOCK,
478
    sub_queue=ServiceBusSubQueue.DEAD_LETTER,
479
    session_id=NEXT_AVAILABLE_SESSION
480
)
481
```