0
# Azure Storage Queue
1

2
Microsoft Azure Queue Storage Client Library for Python providing comprehensive message queuing capabilities for distributed applications. It enables asynchronous communication between application components through reliable message storage with support for millions of messages, visibility timeouts, and global scalability.
3

4
## Package Information
5

6
- **Package Name**: azure-storage-queue
7
- **Language**: Python
8
- **Installation**: `pip install azure-storage-queue`
9
- **Async Support**: `pip install azure-storage-queue[aio]`
10
- **With Encryption**: `pip install azure-storage-queue[encryption]` (includes cryptography dependencies)
11

12
## Core Imports
13

14
```python
15
from azure.storage.queue import QueueServiceClient, QueueClient
16
```
17

18
For message models, retry policies, and authentication:
19

20
```python
21
from azure.storage.queue import (
22
    QueueMessage, 
23
    QueueProperties,
24
    ExponentialRetry,
25
    LinearRetry,
26
    LocationMode,
27
    generate_account_sas,
28
    generate_queue_sas
29
)
30
```
31

32
For encoding policies and storage error codes:
33

34
```python
35
from azure.storage.queue import (
36
    TextBase64EncodePolicy,
37
    TextBase64DecodePolicy,
38
    BinaryBase64EncodePolicy,
39
    BinaryBase64DecodePolicy,
40
    NoEncodePolicy,
41
    NoDecodePolicy,
42
    StorageErrorCode
43
)
44
```
45

46
Async versions:
47

48
```python
49
from azure.storage.queue.aio import QueueServiceClient, QueueClient
50
```
51

52
## Basic Usage
53

54
```python
55
from azure.storage.queue import QueueServiceClient
56

57
# Create service client with connection string
58
service_client = QueueServiceClient.from_connection_string(conn_str="your_connection_string")
59

60
# Create a queue
61
queue_client = service_client.create_queue("myqueue")
62

63
# Send a message
64
queue_client.send_message("Hello, World!")
65

66
# Receive messages
67
messages = queue_client.receive_messages(max_messages=5)
68
for message in messages:
69
    print(f"Message: {message.content}")
70
    # Delete message after processing
71
    queue_client.delete_message(message)
72
```
73

74
## Architecture
75

76
Azure Storage Queue is organized around two main client types:
77

78
- **QueueServiceClient**: Account-level operations for managing queues, service properties, and authentication
79
- **QueueClient**: Queue-specific operations for message handling, queue metadata, and access policies
80

81
Both clients support multiple authentication methods (connection strings, shared keys, SAS tokens, Azure Active Directory) and provide comprehensive retry policies. The library includes both synchronous and asynchronous implementations for different programming models.
82

83
## Capabilities
84

85
### Queue Service Management
86

87
Account-level operations for managing multiple queues, service configuration, and authentication. Provides queue listing, creation, deletion, and service-wide settings management.
88

89
```python { .api }
90
class QueueServiceClient:
91
    def __init__(self, account_url: str, credential=None, **kwargs): ...
92
    def list_queues(self, **kwargs) -> ItemPaged[QueueProperties]: ...
93
    def create_queue(self, name: str, **kwargs) -> QueueClient: ...
94
    def delete_queue(self, queue: Union[str, QueueProperties], **kwargs) -> None: ...
95
    def get_service_properties(self, **kwargs) -> Dict[str, Any]: ...
96
    def set_service_properties(self, **kwargs) -> None: ...
97
```
98

99
[Queue Service Management](./queue-service.md)
100

101
### Queue Operations
102

103
Queue-specific operations including message sending, receiving, peeking, and queue metadata management. Handles individual queue lifecycle and properties.
104

105
```python { .api }
106
class QueueClient:
107
    def __init__(self, account_url: str, queue_name: str, credential=None, **kwargs): ...
108
    def create_queue(self, **kwargs) -> None: ...
109
    def delete_queue(self, **kwargs) -> None: ...
110
    def get_queue_properties(self, **kwargs) -> QueueProperties: ...
111
    def set_queue_metadata(self, metadata: Dict[str, str], **kwargs) -> Dict[str, Any]: ...
112
```
113

114
[Queue Operations](./queue-operations.md)
115

116
### Message Operations
117

118
Comprehensive message handling including sending, receiving, updating, peeking, and deletion. Supports visibility timeouts, message expiration, and batch operations.
119

120
```python { .api }
121
def send_message(self, content: Any, **kwargs) -> QueueMessage: ...
122
def receive_message(self, **kwargs) -> Optional[QueueMessage]: ...
123
def receive_messages(self, **kwargs) -> ItemPaged[QueueMessage]: ...
124
def update_message(self, message: QueueMessage, **kwargs) -> QueueMessage: ...
125
def peek_messages(self, **kwargs) -> List[QueueMessage]: ...
126
def delete_message(self, message: QueueMessage, **kwargs) -> None: ...
127
def clear_messages(self, **kwargs) -> None: ...
128
```
129

130
[Message Operations](./message-operations.md)
131

132
### Authentication and Security
133

134
Shared Access Signature (SAS) generation, access policies, and multiple authentication methods for secure queue access.
135

136
```python { .api }
137
def generate_account_sas(
138
    account_name: str,
139
    account_key: str,
140
    resource_types: Union[ResourceTypes, str],
141
    permission: Union[AccountSasPermissions, str],
142
    expiry: Union[datetime, str],
143
    **kwargs
144
) -> str: ...
145

146
def generate_queue_sas(
147
    account_name: str,
148
    queue_name: str,
149
    account_key: str,
150
    **kwargs
151
) -> str: ...
152
```
153

154
[Authentication and Security](./authentication.md)
155

156
### Data Models and Configuration
157

158
Core data structures, retry policies, message encoding options, and service configuration models.
159

160
```python { .api }
161
class QueueMessage:
162
    id: str
163
    content: Any
164
    pop_receipt: Optional[str]
165
    inserted_on: Optional[datetime]
166
    expires_on: Optional[datetime]
167
    dequeue_count: Optional[int]
168
    next_visible_on: Optional[datetime]
169

170
class QueueProperties:
171
    name: str
172
    metadata: Optional[Dict[str, str]]
173
    approximate_message_count: Optional[int]
174
```
175

176
[Data Models and Configuration](./models-config.md)
177

178
### Async Operations
179

180
Asynchronous implementations of all queue and message operations for high-performance applications requiring non-blocking I/O.
181

182
```python { .api }
183
class QueueServiceClient:  # from azure.storage.queue.aio
184
    async def list_queues(self, **kwargs) -> AsyncItemPaged[QueueProperties]: ...
185
    async def create_queue(self, name: str, **kwargs) -> QueueClient: ...
186
    async def delete_queue(self, queue: Union[str, QueueProperties], **kwargs) -> None: ...
187

188
class QueueClient:  # from azure.storage.queue.aio
189
    async def send_message(self, content: Any, **kwargs) -> QueueMessage: ...
190
    async def receive_message(self, **kwargs) -> Optional[QueueMessage]: ...
191
    def receive_messages(self, **kwargs) -> AsyncItemPaged[QueueMessage]: ...
192
```
193

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

196
## Types
197

198
### Core Types
199

200
```python { .api }
201
from typing import Union, Optional, Dict, List, Any
202
from datetime import datetime
203
from azure.core.paging import ItemPaged
204
```
205

206
### Authentication Types
207

208
```python { .api }
209
class AccountSasPermissions:
210
    read: bool
211
    write: bool
212
    delete: bool
213
    list: bool
214
    add: bool
215
    create: bool
216
    update: bool
217
    process: bool
218

219
class QueueSasPermissions:
220
    read: bool
221
    add: bool
222
    update: bool
223
    process: bool
224

225
class ResourceTypes:
226
    service: bool
227
    container: bool
228
    object: bool
229

230
class Services:
231
    blob: bool
232
    queue: bool
233
    fileshare: bool
234

235
class LocationMode:
236
    PRIMARY: str = "primary"
237
    SECONDARY: str = "secondary"
238
```
239

240
### Retry Policy Types
241

242
```python { .api }
243
class ExponentialRetry:
244
    initial_backoff: int
245
    increment_base: int
246
    retry_total: int
247
    retry_to_secondary: bool
248
    random_jitter_range: int
249

250
class LinearRetry:
251
    backoff: int
252
    retry_total: int
253
    retry_to_secondary: bool
254
    random_jitter_range: int
255
```
256

257
### Error Types
258

259
```python { .api }
260
class StorageErrorCode:
261
    INVALID_MARKER: str
262
    MESSAGE_NOT_FOUND: str
263
    MESSAGE_TOO_LARGE: str
264
    POP_RECEIPT_MISMATCH: str
265
    QUEUE_ALREADY_EXISTS: str
266
    QUEUE_BEING_DELETED: str
267
    QUEUE_DISABLED: str
268
    QUEUE_NOT_EMPTY: str
269
    QUEUE_NOT_FOUND: str
270
```