0
# Container Management
1

2
Container-level operations including creation, deletion, property management, access control, and blob operations within a container. The ContainerClient provides comprehensive management capabilities for Azure Blob Storage containers.
3

4
## Capabilities
5

6
### Client Creation
7

8
Create ContainerClient instances with various authentication methods and from different sources including URLs and connection strings.
9

10
```python { .api }
11
class ContainerClient:
12
    def __init__(self, account_url: str, container_name: str, credential=None, **kwargs):
13
        """
14
        Create a ContainerClient.
15
        
16
        Args:
17
            account_url (str): The URL to the storage account
18
            container_name (str): Name of the container
19
            credential: The credentials for authentication. Can be:
20
                - str: Account key or SAS token string
21
                - dict: Account name and key mapping
22
                - AzureNamedKeyCredential: Named key credential  
23
                - AzureSasCredential: SAS credential
24
                - TokenCredential: Azure AD token credential
25
                - None: For anonymous access or SAS URLs
26
        """
27

28
    @classmethod
29
    def from_container_url(cls, container_url: str, credential=None, **kwargs) -> 'ContainerClient':
30
        """
31
        Create a ContainerClient from a container URL.
32
        
33
        Args:
34
            container_url (str): Complete URL to the container
35
            credential: Optional credential for authentication
36
            
37
        Returns:
38
            ContainerClient: Configured client instance
39
        """
40

41
    @classmethod  
42
    def from_connection_string(cls, conn_str: str, container_name: str, credential=None, **kwargs) -> 'ContainerClient':
43
        """
44
        Create a ContainerClient from a connection string.
45
        
46
        Args:
47
            conn_str (str): Azure Storage connection string
48
            container_name (str): Name of the container
49
            credential: Optional credential to override connection string auth
50
            
51
        Returns:
52
            ContainerClient: Configured client instance
53
        """
54
```
55

56
### Container Lifecycle
57

58
Create, delete, and check container existence. These operations manage the container lifecycle within Azure Blob Storage.
59

60
```python { .api }
61
def create_container(self, metadata=None, public_access=None, **kwargs) -> dict:
62
    """
63
    Create the container.
64
    
65
    Args:
66
        metadata (dict, optional): Container metadata as key-value pairs
67
        public_access (PublicAccess, optional): Public access level for the container
68
        
69
    Returns:
70
        dict: Container creation response with ETag and last modified time
71
    """
72

73
def delete_container(self, **kwargs) -> None:
74
    """
75
    Delete the container and all its blobs.
76
    
77
    Keyword Args:
78
        lease (BlobLeaseClient or str, optional): Required if container has an active lease
79
        if_modified_since (datetime, optional): Delete only if modified since this time
80
        if_unmodified_since (datetime, optional): Delete only if not modified since this time
81
        etag (str, optional): Delete only if ETag matches
82
        match_condition (MatchConditions, optional): ETag matching condition
83
    """
84

85
def exists(self, **kwargs) -> bool:
86
    """
87
    Check whether the container exists.
88
    
89
    Returns:
90
        bool: True if container exists, False otherwise
91
    """
92
```
93

94
### Container Properties and Metadata
95

96
Retrieve and modify container properties, metadata, and access policies.
97

98
```python { .api }
99
def get_container_properties(self, **kwargs) -> ContainerProperties:
100
    """
101
    Get container properties and metadata.
102
    
103
    Returns:
104
        ContainerProperties: Container properties including metadata, lease state, and access policies
105
    """
106

107
def set_container_metadata(self, metadata=None, **kwargs) -> dict:
108
    """
109
    Set container metadata.
110
    
111
    Args:
112
        metadata (dict, optional): Container metadata as key-value pairs
113
        
114
    Returns:
115
        dict: Response with ETag and last modified time
116
    """
117

118
def get_container_access_policy(self, **kwargs) -> dict:
119
    """
120
    Get the container's stored access policies.
121
    
122
    Returns:
123
        dict: Dictionary containing:
124
            - public_access: PublicAccess level
125
            - signed_identifiers: List of AccessPolicy objects
126
    """
127

128
def set_container_access_policy(self, signed_identifiers=None, public_access=None, **kwargs) -> dict:
129
    """
130
    Set the container's access policy and public access level.
131
    
132
    Args:
133
        signed_identifiers (dict, optional): Stored access policies by identifier
134
        public_access (PublicAccess, optional): Public access level
135
        
136
    Returns:
137
        dict: Response with ETag and last modified time
138
    """
139
```
140

141
### Container Leasing
142

143
Acquire and manage leases on containers to prevent concurrent modifications.
144

145
```python { .api }
146
def acquire_lease(self, lease_duration=-1, lease_id=None, **kwargs) -> BlobLeaseClient:
147
    """
148
    Acquire a lease on the container.
149
    
150
    Args:
151
        lease_duration (int): Lease duration in seconds (-1 for infinite)
152
        lease_id (str, optional): Proposed lease identifier
153
        
154
    Returns:
155
        BlobLeaseClient: Lease client for managing the lease
156
    """
157
```
158

159
### Blob Listing and Traversal
160

161
List blobs within the container with various filtering and inclusion options, including hierarchical directory-style traversal.
162

163
```python { .api }
164
def list_blobs(self, name_starts_with=None, include=None, **kwargs) -> ItemPaged[BlobProperties]:
165
    """
166
    List blobs in the container.
167
    
168
    Args:
169
        name_starts_with (str, optional): Filter blobs by name prefix
170
        include (list, optional): Additional properties to include:
171
            - 'snapshots': Include blob snapshots
172
            - 'metadata': Include blob metadata  
173
            - 'uncommittedblobs': Include uncommitted blobs
174
            - 'copy': Include copy properties
175
            - 'deleted': Include soft-deleted blobs
176
            - 'tags': Include blob index tags
177
            - 'versions': Include blob versions
178
            - 'immutabilitypolicy': Include immutability policy
179
            - 'legalhold': Include legal hold status
180
            - 'deletedwithversions': Include deleted blobs with versions
181
            
182
    Returns:
183
        ItemPaged[BlobProperties]: Paginated list of blob properties
184
    """
185

186
def list_blob_names(self, **kwargs) -> ItemPaged[str]:
187
    """  
188
    List blob names only (more efficient than full properties).
189
    
190
    Returns:
191
        ItemPaged[str]: Paginated list of blob names
192
    """
193

194
def walk_blobs(self, name_starts_with=None, include=None, delimiter='/', **kwargs) -> ItemPaged[Union[BlobProperties, BlobPrefix]]:
195
    """
196
    Walk blobs in a directory-like hierarchy using delimiter.
197
    
198
    Args:
199
        name_starts_with (str, optional): Filter by name prefix
200
        include (list, optional): Additional properties to include
201
        delimiter (str): Delimiter for hierarchical listing (default '/')
202
        
203
    Returns:
204
        ItemPaged[Union[BlobProperties, BlobPrefix]]: Paginated list of blobs and prefixes
205
    """
206

207
def find_blobs_by_tags(self, filter_expression: str, **kwargs) -> ItemPaged['FilteredBlob']:
208
    """
209
    Find blobs in the container using tag-based filtering.
210
    
211
    Args:
212
        filter_expression (str): OData filter expression for blob tags
213
        
214
    Returns:
215
        ItemPaged[FilteredBlob]: Paginated list of matching blobs
216
    """
217
```
218

219
### Blob Operations
220

221
Upload, download, and delete blobs through the container client for convenient blob management.
222

223
```python { .api }
224
def upload_blob(self, name: str, data, blob_type='BlockBlob', **kwargs) -> BlobClient:
225
    """
226
    Upload data as a blob in the container.
227
    
228
    Args:
229
        name (str): Name for the blob
230
        data: Data to upload (bytes, str, or file-like object)
231
        blob_type (BlobType): Type of blob to create
232
        
233
    Keyword Args:
234
        length (int, optional): Number of bytes to upload
235
        metadata (dict, optional): Blob metadata
236
        content_type (str, optional): MIME content type
237
        content_encoding (str, optional): Content encoding  
238
        content_language (str, optional): Content language
239
        content_disposition (str, optional): Content disposition
240
        cache_control (str, optional): Cache control header
241
        content_md5 (bytes, optional): MD5 hash of content
242
        validate_content (bool): Validate content integrity
243
        max_concurrency (int): Maximum concurrent uploads
244
        overwrite (bool): Whether to overwrite existing blob
245
        standard_blob_tier (StandardBlobTier, optional): Access tier
246
        tags (dict, optional): Blob index tags
247
        
248
    Returns:
249
        BlobClient: Client for the uploaded blob
250
    """
251

252
def download_blob(self, blob: str, offset=None, length=None, **kwargs) -> StorageStreamDownloader:
253
    """
254
    Download a blob from the container.
255
    
256
    Args:
257
        blob (str): Name of the blob to download
258
        offset (int, optional): Start byte position
259
        length (int, optional): Number of bytes to download
260
        
261
    Returns:
262
        StorageStreamDownloader: Streaming downloader for blob content
263
    """
264

265
def delete_blob(self, blob: str, delete_snapshots=None, **kwargs) -> None:
266
    """
267
    Delete a blob from the container.
268
    
269
    Args:
270
        blob (str): Name of the blob to delete
271
        delete_snapshots (str, optional): How to handle snapshots:
272
            - 'include': Delete blob and all snapshots
273
            - 'only': Delete snapshots but not the blob
274
    """
275
```
276

277
### Batch Operations
278

279
Perform efficient batch operations on multiple blobs within the container.
280

281
```python { .api }
282
def delete_blobs(self, *blobs, **kwargs) -> Iterator[HttpResponse]:
283
    """
284
    Delete multiple blobs in a batch operation.
285
    
286
    Args:
287
        *blobs: Blob names or BlobProperties objects to delete
288
        
289
    Keyword Args:
290
        delete_snapshots (str, optional): How to handle snapshots
291
        raise_on_any_failure (bool): Whether to raise on any failure
292
        
293
    Returns:
294
        Iterator[HttpResponse]: Response for each delete operation
295
    """
296

297
def set_standard_blob_tier_blobs(self, *blobs, **kwargs) -> Iterator[HttpResponse]:
298
    """
299
    Set access tier for multiple standard blobs in batch.
300
    
301
    Args:
302
        *blobs: Tuples of (blob_name, standard_blob_tier) or BlobProperties with tier
303
        
304
    Returns:
305
        Iterator[HttpResponse]: Response for each tier operation
306
    """
307

308
def set_premium_page_blob_tier_blobs(self, *blobs, **kwargs) -> Iterator[HttpResponse]:
309
    """
310
    Set access tier for multiple premium page blobs in batch.
311
    
312
    Args:
313
        *blobs: Tuples of (blob_name, premium_page_blob_tier) or BlobProperties with tier
314
        
315
    Returns:
316
        Iterator[HttpResponse]: Response for each tier operation
317
    """
318
```
319

320
### Blob Client Factory
321

322
Create blob clients for individual blob operations within the container.
323

324
```python { .api }
325
def get_blob_client(self, blob: str, snapshot=None) -> 'BlobClient':
326
    """
327
    Get a BlobClient for a specific blob in this container.
328
    
329
    Args:
330
        blob (str): Name of the blob
331
        snapshot (str, optional): Blob snapshot identifier
332
        
333
    Returns:
334
        BlobClient: Client for blob operations
335
    """
336
```
337

338
### Account Information
339

340
Retrieve storage account information through the container client.
341

342
```python { .api }
343
def get_account_information(self, **kwargs) -> dict:
344
    """
345
    Get information about the storage account.
346
    
347
    Returns:
348
        dict: Account information including account kind and SKU
349
    """
350
```
351

352
## Supporting Data Types
353

354
```python { .api }
355
class PublicAccess:
356
    """Container public access levels."""
357
    OFF: str        # No public access
358
    BLOB: str       # Public read access for blobs only  
359
    CONTAINER: str  # Public read access for container and blobs
360

361
class ContainerProperties:
362
    """Container properties and metadata."""
363
    name: str
364
    last_modified: datetime
365
    etag: str
366
    lease: LeaseProperties
367
    public_access: PublicAccess
368
    has_immutability_policy: bool
369
    deleted: bool
370
    version: str
371
    has_legal_hold: bool
372
    metadata: dict
373
    encryption_scope: ContainerEncryptionScope
374
    immutable_storage_with_versioning_enabled: bool
375

376
class BlobPrefix:
377
    """Blob name prefix for hierarchical listing."""
378
    name: str
379
    service_endpoint: str
380
    container_name: str
381

382
class AccessPolicy:
383
    """Stored access policy for container."""
384
    permission: str
385
    expiry: datetime
386
    start: datetime
387

388
class LeaseProperties:
389
    """Container or blob lease information."""
390
    status: str
391
    state: str
392
    duration: str
393
    
394
class ContainerEncryptionScope:
395
    """Container encryption scope configuration."""
396
    default_encryption_scope: str
397
    deny_encryption_scope_override: bool
398
```