0
# Azure Storage Blob
1
2
A comprehensive Python client library for Azure Blob Storage, Microsoft's object storage solution for storing massive amounts of unstructured data. The library provides rich APIs for managing storage accounts, containers, and blobs with support for various blob types, authentication methods, and both synchronous and asynchronous operations.
3
4
## Package Information
5
6
- **Package Name**: azure-storage-blob
7
- **Language**: Python
8
- **Installation**: `pip install azure-storage-blob`
9
- **Optional Async Support**: `pip install azure-storage-blob[aio]`
10
11
## Core Imports
12
13
```python
14
from azure.storage.blob import BlobServiceClient, ContainerClient, BlobClient
15
```
16
17
Common imports:
18
19
```python
20
from azure.storage.blob import (
21
BlobServiceClient,
22
ContainerClient,
23
BlobClient,
24
BlobType,
25
StandardBlobTier,
26
generate_blob_sas,
27
upload_blob_to_url,
28
download_blob_from_url
29
)
30
```
31
32
Async imports:
33
34
```python
35
from azure.storage.blob.aio import BlobServiceClient, ContainerClient, BlobClient
36
```
37
38
## Basic Usage
39
40
```python
41
from azure.storage.blob import BlobServiceClient
42
43
# Create service client with connection string
44
client = BlobServiceClient.from_connection_string("your_connection_string")
45
46
# Create a container
47
container_client = client.create_container("my-container")
48
49
# Upload a blob using the container client
50
with open("local-file.txt", "rb") as data:
51
blob_client = container_client.upload_blob(
52
name="uploaded-file.txt",
53
data=data
54
)
55
56
# Download a blob
57
blob_client = client.get_blob_client(container="my-container", blob="uploaded-file.txt")
58
with open("downloaded-file.txt", "wb") as download_file:
59
download_file.write(blob_client.download_blob().readall())
60
61
# List containers
62
for container in client.list_containers():
63
print(f"Container: {container.name}")
64
```
65
66
## Architecture
67
68
Azure Storage Blob organizes data in a three-tier hierarchy:
69
70
- **Account**: Top-level namespace with global settings, service properties, and authentication
71
- **Container**: Logical grouping similar to a filesystem directory, with access policies and metadata
72
- **Blob**: Individual data objects of three types (Block, Page, Append) with properties and metadata
73
74
The client library mirrors this hierarchy with corresponding client classes:
75
76
- **BlobServiceClient**: Account-level operations, container management, service configuration
77
- **ContainerClient**: Container-level operations, blob management within a container
78
- **BlobClient**: Individual blob operations, data upload/download, metadata management
79
80
All clients support multiple authentication methods (connection strings, account keys, SAS tokens, Azure AD) and provide both synchronous and asynchronous APIs for integration with various application architectures.
81
82
## Capabilities
83
84
### Service Client Operations
85
86
Account-level operations including authentication, service configuration, container management, and cross-container blob queries. The BlobServiceClient provides the main entry point for interacting with Azure Blob Storage.
87
88
```python { .api }
89
class BlobServiceClient:
90
def __init__(self, account_url: str, credential=None, **kwargs): ...
91
def from_connection_string(cls, conn_str: str, credential=None, **kwargs) -> BlobServiceClient: ...
92
def get_service_properties(self, **kwargs): ...
93
def set_service_properties(self, analytics_logging=None, hour_metrics=None, minute_metrics=None, cors=None, target_version=None, delete_retention_policy=None, static_website=None, **kwargs): ...
94
def list_containers(self, name_starts_with=None, include_metadata=False, **kwargs): ...
95
def create_container(self, name: str, metadata=None, public_access=None, **kwargs): ...
96
def delete_container(self, container: str, **kwargs): ...
97
def get_container_client(self, container: str) -> ContainerClient: ...
98
def get_blob_client(self, container: str, blob: str, snapshot=None) -> BlobClient: ...
99
```
100
101
[Service Client Operations](./service-client.md)
102
103
### Container Management
104
105
Container-level operations including creation, deletion, property management, access control, and blob listing. ContainerClient provides comprehensive container management capabilities.
106
107
```python { .api }
108
class ContainerClient:
109
def __init__(self, account_url: str, container_name: str, credential=None, **kwargs): ...
110
def from_container_url(cls, container_url: str, credential=None, **kwargs) -> ContainerClient: ...
111
def create_container(self, metadata=None, public_access=None, **kwargs): ...
112
def delete_container(self, **kwargs): ...
113
def get_container_properties(self, **kwargs): ...
114
def set_container_metadata(self, metadata=None, **kwargs): ...
115
def list_blobs(self, name_starts_with=None, include=None, **kwargs): ...
116
def upload_blob(self, name: str, data, blob_type=BlobType.BLOCKBLOB, **kwargs): ...
117
def download_blob(self, blob: str, offset=None, length=None, **kwargs): ...
118
def delete_blob(self, blob: str, delete_snapshots=None, **kwargs): ...
119
```
120
121
[Container Management](./container-client.md)
122
123
### Blob Operations
124
125
Individual blob operations including upload, download, properties management, and blob-type specific operations. BlobClient provides comprehensive blob management for all blob types.
126
127
```python { .api }
128
class BlobClient:
129
def __init__(self, account_url: str, container_name: str, blob_name: str, snapshot=None, credential=None, **kwargs): ...
130
def from_blob_url(cls, blob_url: str, credential=None, **kwargs) -> BlobClient: ...
131
def upload_blob(self, data, blob_type=BlobType.BLOCKBLOB, **kwargs): ...
132
def download_blob(self, offset=None, length=None, **kwargs) -> StorageStreamDownloader: ...
133
def delete_blob(self, delete_snapshots=None, **kwargs): ...
134
def get_blob_properties(self, **kwargs): ...
135
def set_blob_metadata(self, metadata=None, **kwargs): ...
136
def create_snapshot(self, **kwargs): ...
137
def start_copy_from_url(self, source_url: str, **kwargs): ...
138
```
139
140
[Blob Operations](./blob-client.md)
141
142
### Shared Access Signatures
143
144
Generate time-limited, secure access tokens for Azure Storage resources without exposing account keys. SAS tokens enable granular permission control for external access.
145
146
```python { .api }
147
def generate_account_sas(account_name: str, account_key: str, resource_types, permission, expiry, start=None, ip=None, protocol=None, **kwargs) -> str: ...
148
def generate_container_sas(account_name: str, container_name: str, account_key=None, user_delegation_key=None, permission=None, expiry=None, start=None, policy_id=None, ip=None, protocol=None, **kwargs) -> str: ...
149
def generate_blob_sas(account_name: str, container_name: str, blob_name: str, snapshot=None, version_id=None, account_key=None, user_delegation_key=None, permission=None, expiry=None, start=None, policy_id=None, ip=None, protocol=None, **kwargs) -> str: ...
150
```
151
152
[Shared Access Signatures](./sas-generation.md)
153
154
### Blob Types and Storage Tiers
155
156
Azure Blob Storage supports three blob types optimized for different scenarios, along with access tiers for cost optimization. Each blob type provides specific capabilities for different data patterns.
157
158
```python { .api }
159
class BlobType:
160
BLOCKBLOB: str
161
PAGEBLOB: str
162
APPENDBLOB: str
163
164
class StandardBlobTier:
165
HOT: str
166
COOL: str
167
COLD: str
168
ARCHIVE: str
169
170
class PremiumPageBlobTier:
171
P4: str
172
P6: str
173
P10: str
174
P15: str
175
P20: str
176
P30: str
177
P40: str
178
P50: str
179
P60: str
180
```
181
182
[Blob Types and Storage Tiers](./blob-types-tiers.md)
183
184
### Async Operations
185
186
Asynchronous versions of all client classes for high-performance, concurrent operations. The async clients provide identical APIs with async/await patterns for scalable applications.
187
188
```python { .api }
189
# All async clients have the same methods as sync versions but with async/await
190
from azure.storage.blob.aio import BlobServiceClient, ContainerClient, BlobClient
191
192
async def example():
193
async with BlobServiceClient.from_connection_string(conn_str) as client:
194
async for container in client.list_containers():
195
print(container.name)
196
```
197
198
[Async Operations](./async-operations.md)
199
200
### Utility Functions
201
202
Convenient helper functions for common blob operations without requiring client instantiation. These functions provide simplified access for basic upload and download scenarios.
203
204
```python { .api }
205
def upload_blob_to_url(blob_url: str, data, credential=None, **kwargs) -> dict: ...
206
def download_blob_from_url(blob_url: str, output, credential=None, **kwargs) -> None: ...
207
```
208
209
[Utility Functions](./utility-functions.md)
210
211
## Data Models
212
213
### Core Data Types
214
215
```python { .api }
216
class BlobProperties:
217
"""Comprehensive blob properties and metadata."""
218
name: str
219
container: str
220
snapshot: str
221
blob_type: BlobType
222
last_modified: datetime
223
etag: str
224
size: int
225
content_type: str
226
content_encoding: str
227
content_language: str
228
content_disposition: str
229
cache_control: str
230
content_md5: bytes
231
metadata: dict
232
lease: LeaseProperties
233
copy: CopyProperties
234
creation_time: datetime
235
archive_status: str
236
rehydrate_priority: str
237
encryption_key_sha256: str
238
encryption_scope: str
239
request_server_encrypted: bool
240
object_replication_source_properties: list
241
object_replication_destination_policy: str
242
tag_count: int
243
tags: dict
244
immutability_policy: ImmutabilityPolicy
245
has_legal_hold: bool
246
has_versions_only: bool
247
248
class ContainerProperties:
249
"""Container metadata and properties."""
250
name: str
251
last_modified: datetime
252
etag: str
253
lease: LeaseProperties
254
public_access: PublicAccess
255
has_immutability_policy: bool
256
deleted: bool
257
version: str
258
has_legal_hold: bool
259
metadata: dict
260
encryption_scope: ContainerEncryptionScope
261
immutable_storage_with_versioning_enabled: bool
262
263
class StorageStreamDownloader:
264
"""Streaming download with iteration support."""
265
def readall(self) -> bytes: ...
266
def readinto(self, stream) -> int: ...
267
def download_to_stream(self, stream) -> None: ...
268
def chunks(self) -> Iterator[bytes]: ...
269
def content_as_bytes(self) -> bytes: ...
270
def content_as_text(self, encoding: str = 'utf-8') -> str: ...
271
```