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
```