Azure Storage Blobs client library for Python

Azure Blob storage is Microsoft's object storage solution for the cloud. Blob storage is optimized for storing massive amounts of unstructured data, such as text or binary data.

Blob storage is ideal for:

• Serving images or documents directly to a browser
• Storing files for distributed access
• Streaming video and audio
• Storing data for backup and restore, disaster recovery, and archiving
• Storing data for analysis by an on-premises or Azure-hosted service

Source code | Package (PyPI) | Package (Conda) | API reference documentation | Product documentation | Samples

Getting started

Prerequisites

• Python 3.9 or later is required to use this package. For more details, please read our page on Azure SDK for Python version support policy.
• You must have an Azure subscription and an Azure storage account to use this package.

Install the package

Install the Azure Storage Blobs client library for Python with pip:

pip install azure-storage-blob

Create a storage account

If you wish to create a new storage account, you can use the Azure Portal, Azure PowerShell, or Azure CLI:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

Create the client

The Azure Storage Blobs client library for Python allows you to interact with three types of resources: the storage account itself, blob storage containers, and blobs. Interaction with these resources starts with an instance of a client. To create a client object, you will need the storage account's blob service account URL and a credential that allows you to access the storage account:

from azure.storage.blob import BlobServiceClient

service = BlobServiceClient(account_url="https://<my-storage-account-name>.blob.core.windows.net/", credential=credential)

Looking up the account URL

You can find the storage account's blob service URL using the Azure Portal, Azure PowerShell, or Azure CLI:

# Get the blob service account url for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.blob"

Types of credentials

The credential parameter may be provided in a number of different forms, depending on the type of authorization you wish to use:

1. To use an Azure Active Directory (AAD) token credential, provide an instance of the desired credential type obtained from the azure-identity library. For example, DefaultAzureCredential can be used to authenticate the client.

   This requires some initial setup:

   • Install azure-identity
   • Register a new AAD application and give permissions to access Azure Storage
   • Grant access to Azure Blob data with RBAC in the Azure Portal
   • Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET

   Use the returned token credential to authenticate the client:

   from azure.identity import DefaultAzureCredential
   from azure.storage.blob import BlobServiceClient
   token_credential = DefaultAzureCredential()
   
   blob_service_client = BlobServiceClient(
       account_url="https://<my_account_name>.blob.core.windows.net",
       credential=token_credential
   )
   

2. To use a shared access signature (SAS) token, provide the token as a string. If your account URL includes the SAS token, omit the credential parameter. You can generate a SAS token from the Azure Portal under "Shared access signature" or use one of the generate_sas() functions to create a sas token for the storage account, container, or blob:

   from datetime import datetime, timedelta
   from azure.storage.blob import BlobServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions
   
   sas_token = generate_account_sas(
       account_name="<storage-account-name>",
       account_key="<account-access-key>",
       resource_types=ResourceTypes(service=True),
       permission=AccountSasPermissions(read=True),
       expiry=datetime.utcnow() + timedelta(hours=1)
   )
   
   blob_service_client = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential=sas_token)
   

3. To use a storage account shared key (aka account key or access key), provide the key as a string. This can be found in the Azure Portal under the "Access Keys" section or by running the following Azure CLI command:

   az storage account keys list -g MyResourceGroup -n MyStorageAccount

   Use the key as the credential parameter to authenticate the client:

   from azure.storage.blob import BlobServiceClient
   service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential="<account_access_key>")
   

   If you are using customized url (which means the url is not in this format <my_account_name>.blob.core.windows.net), please instantiate the client using the credential below:

   from azure.storage.blob import BlobServiceClient
   service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net",
      credential={"account_name": "<your_account_name>", "account_key":"<account_access_key>"})
   

4. To use anonymous public read access, simply omit the credential parameter.

Creating the client from a connection string

Depending on your use case and authorization method, you may prefer to initialize a client instance with a storage connection string instead of providing the account URL and credential separately. To do this, pass the storage connection string to the client's from_connection_string class method:

from azure.storage.blob import BlobServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = BlobServiceClient.from_connection_string(conn_str=connection_string)

The connection string to your storage account can be found in the Azure Portal under the "Access Keys" section or by running the following CLI command:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Key concepts

The following components make up the Azure Blob Service:

• The storage account itself
• A container within the storage account
• A blob within a container

The Azure Storage Blobs client library for Python allows you to interact with each of these components through the use of a dedicated client object.

Clients

Four different clients are provided to interact with the various components of the Blob Service:

1. BlobServiceClient - this client represents interaction with the Azure storage account itself, and allows you to acquire preconfigured client instances to access the containers and blobs within. It provides operations to retrieve and configure the account properties as well as list, create, and delete containers within the account. To perform operations on a specific container or blob, retrieve a client using the get_container_client or get_blob_client methods.
2. ContainerClient - this client represents interaction with a specific container (which need not exist yet), and allows you to acquire preconfigured client instances to access the blobs within. It provides operations to create, delete, or configure a container and includes operations to list, upload, and delete the blobs within it. To perform operations on a specific blob within the container, retrieve a client using the get_blob_client method.
3. BlobClient - this client represents interaction with a specific blob (which need not exist yet). It provides operations to upload, download, delete, and create snapshots of a blob, as well as specific operations per blob type.
4. BlobLeaseClient - this client represents lease interactions with a ContainerClient or BlobClient. It provides operations to acquire, renew, release, change, and break a lease on a specified resource.

Async Clients

This library includes a complete async API supported on Python 3.5+. To use it, you must first install an async transport, such as aiohttp. See azure-core documentation for more information.

Async clients and credentials should be closed when they're no longer needed. These objects are async context managers and define async close methods.

Blob Types

Once you've initialized a Client, you can choose from the different types of blobs:

• Block blobs store text and binary data, up to approximately 4.75 TiB. Block blobs are made up of blocks of data that can be managed individually
• Append blobs are made up of blocks like block blobs, but are optimized for append operations. Append blobs are ideal for scenarios such as logging data from virtual machines
• Page blobs store random access files up to 8 TiB in size. Page blobs store virtual hard drive (VHD) files and serve as disks for Azure virtual machines

Examples

The following sections provide several code snippets covering some of the most common Storage Blob tasks, including:

• Create a container
• Uploading a blob
• Downloading a blob
• Enumerating blobs

Note that a container must be created before to upload or download a blob.

Create a container

Create a container from where you can upload or download blobs.

from azure.storage.blob import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

container_client.create_container()

Use the async client to create a container

from azure.storage.blob.aio import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

await container_client.create_container()

Uploading a blob

Upload a blob to your container

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    blob.upload_blob(data)

Use the async client to upload a blob

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

Downloading a blob

Download a blob from your container

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    blob_data = blob.download_blob()
    blob_data.readinto(my_blob)

Download a blob asynchronously

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.readall()
    my_blob.write(data)

Enumerating blobs

List the blobs in your container

from azure.storage.blob import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = container.list_blobs()
for blob in blob_list:
    print(blob.name + '\n')

List the blobs asynchronously

from azure.storage.blob.aio import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = []
async for blob in container.list_blobs():
    blob_list.append(blob)
print(blob_list)

Optional Configuration

Optional keyword arguments that can be passed in at the client and per-operation level.

Retry Policy configuration

Use the following keyword arguments when instantiating a client to configure the retry policy:

• retry_total (int): Total number of retries to allow. Takes precedence over other counts. Pass in retry_total=0 if you do not want to retry on requests. Defaults to 10.
• retry_connect (int): How many connection-related errors to retry on. Defaults to 3.
• retry_read (int): How many times to retry on read errors. Defaults to 3.
• retry_status (int): How many times to retry on bad status codes. Defaults to 3.
• retry_to_secondary (bool): Whether the request should be retried to secondary, if able. This should only be enabled of RA-GRS accounts are used and potentially stale data can be handled. Defaults to False.

Encryption configuration

Use the following keyword arguments when instantiating a client to configure encryption:

• require_encryption (bool): If set to True, will enforce that objects are encrypted and decrypt them.
• encryption_version (str): Specifies the version of encryption to use. Current options are '2.0' or '1.0' and the default value is '1.0'. Version 1.0 is deprecated, and it is highly recommended to use version 2.0.
• key_encryption_key (object): The user-provided key-encryption-key. The instance must implement the following methods:
  • wrap_key(key)--wraps the specified key using an algorithm of the user's choice.
  • get_key_wrap_algorithm()--returns the algorithm used to wrap the specified symmetric key.
  • get_kid()--returns a string key id for this key-encryption-key.
• key_resolver_function (callable): The user-provided key resolver. Uses the kid string to return a key-encryption-key implementing the interface defined above.

Other client / per-operation configuration

Other optional configuration keyword arguments that can be specified on the client or per-operation.

Client keyword arguments:

• connection_timeout (int): The number of seconds the client will wait to establish a connection to the server. Defaults to 20 seconds.
• read_timeout (int): The number of seconds the client will wait, between consecutive read operations, for a response from the server. This is a socket level timeout and is not affected by overall data size. Client-side read timeouts will be automatically retried. Defaults to 60 seconds.
• transport (Any): User-provided transport to send the HTTP request.

Per-operation keyword arguments:

• raw_response_hook (callable): The given callback uses the response returned from the service.
• raw_request_hook (callable): The given callback uses the request before being sent to service.
• client_request_id (str): Optional user specified identification of the request.
• user_agent (str): Appends the custom value to the user-agent header to be sent with the request.
• logging_enable (bool): Enables logging at the DEBUG level. Defaults to False. Can also be passed in at the client level to enable it for all requests.
• logging_body (bool): Enables logging the request and response body. Defaults to False. Can also be passed in at the client level to enable it for all requests.
• headers (dict): Pass in custom headers as key, value pairs. E.g. headers={'CustomValue': value}

Troubleshooting

General

Storage Blob clients raise exceptions defined in Azure Core.

This list can be used for reference to catch thrown exceptions. To get the specific error code of the exception, use the error_code attribute, i.e, exception.error_code.

Logging

This library uses the standard logging library for logging. Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO level.

Detailed DEBUG level logging, including request/response bodies and unredacted headers, can be enabled on a client with the logging_enable argument:

import sys
import logging
from azure.storage.blob import BlobServiceClient

# Create a logger for the 'azure.storage.blob' SDK
logger = logging.getLogger('azure.storage.blob')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = BlobServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Similarly, logging_enable can enable detailed logging for a single operation, even when it isn't enabled for the client:

service_client.get_service_stats(logging_enable=True)

Next steps

More sample code

Get started with our Blob samples.

Several Storage Blobs Python SDK samples are available to you in the SDK's GitHub repository. These samples provide example code for additional scenarios commonly encountered while working with Storage Blobs:

• blob_samples_container_access_policy.py (async version) - Examples to set Access policies:

  • Set up Access Policy for container

• blob_samples_hello_world.py (async version) - Examples for common Storage Blob tasks:

  • Set up a container
  • Create a block, page, or append blob
  • Upload blobs
  • Download blobs
  • Delete blobs

• blob_samples_authentication.py (async version) - Examples for authenticating and creating the client:

  • From a connection string
  • From a shared access key
  • From a shared access signature token
  • From active directory

• blob_samples_service.py (async version) - Examples for interacting with the blob service:

  • Get account information
  • Get and set service properties
  • Get service statistics
  • Create, list, and delete containers
  • Get the Blob or Container client

• blob_samples_containers.py (async version) - Examples for interacting with containers:

  • Create a container and delete containers
  • Set metadata on containers
  • Get container properties
  • Acquire a lease on container
  • Set an access policy on a container
  • Upload, list, delete blobs in container
  • Get the blob client to interact with a specific blob

• blob_samples_common.py (async version) - Examples common to all types of blobs:

  • Create a snapshot
  • Delete a blob snapshot
  • Soft delete a blob
  • Undelete a blob
  • Acquire a lease on a blob
  • Copy a blob from a URL

Additional documentation

For more extensive documentation on Azure Blob storage, see the Azure Blob storage documentation on learn.microsoft.com.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Release History

12.32.0b1 (2026-11-04)

Breaking Changes

• Custom transports that use legacy azure-core Request/Response types will no longer be supported and may now cause errors if used. Please ensure custom transports are utilizing types from azure.core.rest.
• Changed the default max_single_put_size from 64 MiB to 4 MiB. This means uploads greater than 4 MiB will now be performed in multiple requests instead of a single request. This may result in more requests and a block blob with more blocks than in previous versions. To restore the previous behavior, pass max_single_put_size = 64 * 1024 * 1024 when constructing the client.
• Changed the default max_single_get_size from 32 MiB to 4 MiB. This means the initial download request will now be 4 MiB rather than 32 MiB which may result in more requests than previous versions depending on blob size. This also means some blob downloads may use parallel requests when they were not previously, if max_concurrency is set greater than 1. To restore the previous behavior, pass max_single_get_size = 32 * 1024 * 1024 when constructing the client.

Features Added

• Added support for service versions 2026-12-06 and 2027-03-07.
• Added opt-in client session-based authentication via the new use_session keyword argument. When enabled, eligible blob download requests are authenticated with a short-lived, per-container session credential obtained from the service rather than the bearer token. Requires a TokenCredential. Sessions are managed by a session provider, which can be shared across clients via the session_provider keyword, and the account name used for signing can be set explicitly with session_account_name.

Bugs Fixed

• Fixed an issue with the new generation where listing page ranges for an empty page blob could raise a ValueError instead of returning an empty list.
• Fixed an issue where a SAS generated for a blob name containing a backslash (\) was invalid because the backslash was not normalized to a forward slash when building the signed resource.

Other Changes

• Added nanoarrow>=0.7.0 as a required dependency.
• Added public SignedIdentifier model and updated ContainerClient.get_container_access_policy and azure.storage.blob.aio.ContainerClient.get_container_access_policy to return public models instead of generated internal types.
• ContainerClient's list_blobs, list_blob_names, and walk_blobs now use Arrow by default. Pass response_format="xml" to use the previous behavior.
• Migrated generated code to use the new TypeSpec generator.

12.31.1 (2026-10-29)

Bugs Fixed

• Fixed UTC conversion of timezone-aware datetimes in generate_account_sas, generate_container_sas, generate_blob_sas, and BlobServiceClient.get_user_delegation_key (sync and async). Datetimes without timezone information continue to be treated as UTC.
• Fixed an issue where certain headers were not being properly redacted when DEBUG logging was enabled.

12.31.0 (2026-09-30)

This version and all future versions will require Python 3.10+. Python 3.9 is no longer supported.

Features Added

• Stable release of features from 12.31.0b1
• Added list support to BlobSasPermissions for use with directory-scoped SAS tokens.

Bugs Fixed

• Fixed an issue where destination_snapshot on a blob's copy properties was always None when listing blobs with response_format="arrow".

12.30.3 (2026-09-22)

Bugs Fixed

• Async clients now reject header names and values containing a \r or \n when sending a batch request, matching the behavior of the sync clients.

12.30.2 (2026-09-16)

Bugs Fixed

• Fixed an issue where a header name or value containing a \r or \n was written directly into a batch request body. Such headers are now rejected with a ValueError.

12.30.1 (2026-08-27)

Bugs Fixed

• Fixed a bug where client-side encryption 2.0 could not detect a rearrangement of otherwise-untampered authenticated regions in blob content. This is now detected and exceptions are thrown. For data recovery purposes, this behavior can be reverted by setting the "AZURE_STORAGE_CSE_V2_ALLOW_MISORDERED_AUTH_REGIONS" environment variable.
• Fixed a bug in client-side encryption where version downgrades, and other metadata tampering, was only detected at the start of a download.

12.31.0b1 (2026-08-10)

Features Added

• Added support for service version 2026-10-06.
• Added support for parsing List Blobs responses in Apache Arrow format by passing response_format="arrow" keyword to ContainerClient's list_blobs, walk_blobs, and list_blob_names APIs (response_format defaults to "auto", and "auto" currently means "xml"). The use of "response_format=arrow" requires nanoarrow to be installed. This change also enables the new end_before keyword for range-based listing.
• Added access tier information to the response of BlobClient's download_blob API. The blob_tier, blob_tier_inferred, blob_tier_change_time, and smart_access_tier properties are now populated on the downloaded blob's properties.
• The service-calculated CRC64 is now surfaced as content_crc64 on the response of BlobClient upload operations (stage_block, stage_block_from_url, upload_page, upload_pages_from_url, append_block, append_block_from_url, upload_blob, and upload_blob_from_url) in addition to content_md5 when a content MD5 is provided with the request.

Other Changes

• Partitioned upload via upload_blob with Block Blobs will now generate random, unique block ids for each block rather than using a sequential count. The length of the new block ids will be the same as previous versions to ensure backwards compatibility.

12.30.0 (2026-06-08)

Features Added

• Stable release of features from 12.30.0b1

12.29.0 (2026-05-14)

Features Added

• Stable release of features from 12.29.0b1

Bugs Fixed

• Fixed an issue where BlobClient's download_blob did not retry upon ServiceResponseError and ServiceResponseTimeoutError exceptions
• Fixed various issues with configuring logging via logging_enable and logging_body keywords on a per-request basis and with retries. Prior to this fix logging may have not behaved as expected, especially on retries.
• Fix a potential memory leak caused by improper exception handling that could occur under rare circumstances.

12.30.0b1 (2026-04-01)

Features Added

• Added support for service version 2026-06-06.
• Added support for connection strings and account_urls to accept URLs with -ipv6 and -dualstack suffixes for BlobServiceClient, ContainerClient, and BlobClient.
• Added support for create permission in BlobSasPermissions for stage_block, stage_block_from_url, and commit_block_list.
• Added support for a new Smart access tier to StandardBlobTier used in BlobClient.set_standard_blob_tier, which is optimized to automatically determine the most cost-effective access with no performance impact. When set, BlobProperties.smart_access_tier will reveal the service's current access tier choice between Hot, Cool, and Archive.
• Added support for is_directory keyword in generate_blob_sas that generates directory-level SAS for blobs.

Other Changes

• Consolidated the behavior of max_concurrency=None by defaulting to the shared DEFAULT_MAX_CONCURRENCY constant.

12.29.0b1 (2026-01-27)

Features Added

• Added support for service version 2026-04-06.
• Added support for error code INCREMENTAL_COPY_OF_EARLIER_SNAPSHOT_NOT_ALLOWED. This replaces INCREMENTAL_COPY_OF_EARLIER_VERSION_SNAPSHOT_NOT_ALLOWED which has been deprecated.
• Added support for the keywords access_tier_if_modified_since and access_tier_if_unmodified_since to conditionally perform BlobClient.delete_blob operation.
• Added support for the keyword source_cpk for BlobClient's upload_blob_from_url, stage_block_from_url, upload_pages_from_url, and append_block_from_url APIs to re-encrypt data automatically by the service through a CustomerProvidedEncryptionKey.
• Added support for the keyword user_delegation_tid to BlobServiceClient.get_user_delegation_key API, which can be used in generate_blob_sas and generate_container_sas to specify the Tenant ID that is authorized to use the generated SAS URL. Note that user_delegation_tid must be used together with user_delegation_oid.
• Added support for the keyword request_headers to generate_blob_sas and generate_container_sas, which specifies a set of headers and their corresponding values that must be present in the request header when using the generated SAS.
• Added support for the keyword request_query_params to generate_blob_sas and generate_container_sas, which specifies a set of query parameters and their corresponding values that must be present in the request URL when using the generated SAS.

Other Changes

• Bumped minimum azure-core dependency to 1.37.0.

12.28.0 (2026-01-06)

Features Added

• Stable release of features from 12.28.0b1

Other Changes

• Changed the default connection_data_block_size for all clients from 4 KiB to 256 KiB. This should result in significantly better throughput on large file downloads for most environments.

12.28.0b1 (2025-12-04)

Features Added

• Added support for service version 2026-02-06.
• Added support for the keywords if_modified_since, if_unmodified_since, etag, and match_condition to conditionally perform BlobClient's set_blob_tags and get_blob_tags operations.
• Added support for the keyword start_from in ContainerClient's list_blobs, list_blob_names, and walk_blobs APIs, which specifies the full path to start listing paths from.
• Added support for the keyword user_delegation_oid to generate_blob_sas and generate_container_sas, which specifies the Entra ID of the user that is authorized to use the generated SAS URL.
• Added support for UseDevelopmentStorage=true; as a valid connection string for Azurite.
• Added the ability to skip auto decompression on BlobClient.download_blob via the decompress keyword.

12.27.1 (2025-10-29)

Bugs Fixed

• Fixed MyPy attr-defined errors for BlobClient.

12.27.0 (2025-10-15)

Features Added

• Stable release of features from 12.27.0b1

Other Changes

• Migrated any previously documented kwarg arguments to be named keywords. Some public types may have been adjusted if they were previously erroneous or incomplete.
• Removed __enter__ and __exit__ attributes for all asynchronous client objects for raising explicit TypeError, and let the AttributeError raise directly.

12.26.0 (2025-07-16)

Features Added

• Stable release of features from 12.26.0b1

Bugs Fixed

• Fixed an issue where BlobClient's start_copy_from_url with incremental_copy=True results in TypeError.

12.27.0b1 (2025-06-12)

This version and all future versions will require Python 3.9+. Python 3.8 is no longer supported.

Features Added

• Added support for service version 2025-11-05.
• Added support for better error handling for copy operations.

12.26.0b1 (2025-05-06)

Features Added

• Added support for service version 2025-07-05.
• Added support for OAuth authentication in ContainerClient's get_container_access_policy and set_container_access_policy APIs.
• Added support for the keyword source_token_intent when copying from file share to blob and authenticated via TokenCredential for the following BlobClient APIs: upload_blob_from_url, start_copy_from_url, stage_block_from_url, upload_pages_from_url, and append_block_from_url.
• Added support for query_blob in the asynchronous BlobClient.

12.25.1 (2025-03-27)

Other Changes

• Updated dependency for azure-storage-file-datalake type hints.

12.25.0 (2025-03-11)

Features Added

• Stable release of features from 12.25.0b1

12.25.0b1 (2025-02-11)

Features Added

• Added support for service version 2025-05-05.

12.24.1 (2025-01-22)

Bugs Fixed

• Fixed an issue where custom transports may encounter AttributeError on certain requests.
• Fixed an issue where StorageStreamDownloader(chars=-1) may not return all data.

12.24.0 (2024-11-13)

Features Added

• Stable release of features from 12.24.0b1

12.24.0b1 (2024-10-10)

Features Added

• Added support for service version 2025-01-05.
• Added support for passing metadata to upload_blob_from_url via the new metadata keyword.
• Added support for set_immutability_policy, delete_immutability_policy and set_legal_hold for Blob snapshots and versions.

12.23.1 (2024-09-25)

Features Added

• Added support for decryption of Blobs encrypted using client-side encryption version 2.1.

12.23.0 (2024-09-17)

Features Added

• Stable release of features from 12.23.0b1

Bugs Fixed

• Fixed an issue with batch APIs when using Azurite.

12.23.0b1 (2024-08-07)

Features Added

• Added support for service version 2024-11-04.

Other Changes

• Bumped minimum azure-core dependency to 1.30.0.

12.22.0 (2024-08-06)

Other Changes

• Updated type hints across the entire package and enabled MyPy to run during CI. Some public types may have been adjusted if they were previously erroneous or incomplete.

12.21.0 (2024-07-18)

Features Added

• Stable release of features from 12.21.0b1
• Added new chars keyword to the StorageStreamDownloader.read method to support reading an arbitrary number of characters from the stream rather than bytes. This can only be used when encoding is specified on download_blob but can help prevent decoding errors in certain scenarios.

12.21.0b1 (2024-06-11)

Features Added

• Added support for service version 2024-08-04.

12.20.0 (2024-05-07)

Features Added

• Stable release of features from 12.20.0b1

12.20.0b1 (2024-04-16)

This version and all future versions will require Python 3.8+. Python 3.7 is no longer supported.

Features Added

• Added support for service version 2024-05-04.
• The services parameter has been added to the generate_account_sas API, which enables the ability to generate SAS tokens to be used with multiple services. By default, the SAS token service scope will default to the current service.

Bugs Fixed

• Bumped dependency of typing-extensions to >=4.6.0 to avoid potential TypeError with typing.TypeVar on Python 3.12.
• Fixed an issue where authentication errors could raise AttributeError instead of ClientAuthenticationError when using async OAuth credentials.
• Fixed a typing issue which incorrectly typed the readinto API. The correct input type is IO[bytes].
• Fixed a typo in the initialization of completion_time for the CopyProperties model.
• Fixed a couple of issues with upload_blob when using Iterators/Generators as the data input.

Other Changes

• Passing prefix to the following ContainerClient APIs now raises a ValueError: list_blobs, list_blobs_names, and walk_blobs. This change was made to avoid confusion for filtering results. The name_starts_with parameter is the correct parameter to pass for filtering.

12.19.1 (2024-03-05)

Bugs Fixed

• Fixed an issue where under rare circumstances, full downloads of sparse Page Blobs could result in the downloaded content containing up to one "chunk" of extra \x00 at the end due to an optimization error.

12.19.0 (2023-11-07)

Features Added

• Stable release of features from 12.19.0b1

12.19.0b1 (2023-10-17)

Features Added

• Added support for service version 2023-11-03.
• Added audience as an optional keyword that can be specified on APIs that have a credential parameter. This keyword only has an effect when the credential provided is of type TokenCredential.

Bugs Fixed

• Deprecated BlobProperties as a valid input type to the blob parameter on the following APIs: BlobServiceClient's get_blob_client, ContainerClient's delete_blob, download_blob, and get_blob_client. This deprecation change also applies to the name parameter on ContainerClient's upload_blob API. This change applies to both sync and async packages but does not apply to the batch equivalent of any of the listed APIs. If a BlobProperties is provided, a deprecation warning is raised.

12.18.3 (2023-10-10)

Bugs Fixed

• Fixed an issue when an invalid type was provided for credential during client construction, the __str__ of the object would be present in the exception message and therefore potentially logged.

12.18.2 (2023-09-25)

Bugs Fixed

• Fixed an issue where user_agent was being ignored on upload_blob or download_blob if client was configured for encryption.

12.18.1 (2023-09-13)

Bugs Fixed

• Fixed breaking KeyError: 'sdk_moniker' in create_configuration. NOTE: This is not an exported method and therefore should not be imported/called directly.

12.18.0 (2023-09-12)

Features Added

• Stable release of features from 12.18.0b1

12.18.0b1 (2023-08-08)

Features Added

• Added support for service versions 2023-05-03 and 2023-08-03.
• Added version_id as a client constructor parameter to BlobClient. This change makes BlobClients version-aware, such that all APIs that accept version_id will operate on the version ID provided during client construction by default.
• Added optional keyword version_id to get_blob_client APIs which, if provided, will result in a version-aware BlobClient in which all APIs that accept version_id will operate on the version ID provided to the get_blob_client API call by default.

12.17.0 (2023-07-11)

Features Added

• Stable release of features from 12.17.0b1

12.17.0b1 (2023-05-30)

Features Added

• Added support for service version 2023-01-03.
• Content length limit increased from 4 MiB to 100 MiB for append_block and append_block_from_url APIs and their async equivalents.

12.16.0 (2023-04-12)

Features Added

• Stable release of features from 12.16.0b1

12.16.0b1 (2023-03-28)

Features Added

• Added support for service version 2022-11-02.

12.15.0 (2023-02-22)

Features Added

• Stable release of features from 12.15.0b1
• The download_blob API now returns creation_time on the download response.

12.15.0b1 (2023-02-02)

Features Added

• Added support for service version 2021-12-02.
• Added support for new blob tier, Cold.
• Added support for AsyncIterable as data type for async blob upload.

Bugs Fixed

• Changed how async streams are detected on async upload_blob to increase compatiblity with different types.

Other Changes

• Removed msrest dependency.
• Added typing-extensions>=4.0.1 as a dependency.
• Added isodate>=0.6.1 as a dependency.
• Added extra dependency aio for installing optional async dependencies. Use pip install azure-storage-blob[aio] to install.

12.14.1 (2022-10-18)

Bugs Fixed

• Fixed possible ValueError for invalid content range that gets raised when downloading empty blobs through Azurite.

12.14.0 (2022-10-11)

Features Added

• Stable release of features from 12.14.0b1 and 12.14.0b2.

Bugs Fixed

• Fixed an issue where calling download_blob with an invalid base64-encoded account key would cause an AttributeError rather than the proper AzureSigningError.

Other Changes

• Changed the default value for read_timeout to 60 seconds for all clients.

12.14.0b2 (2022-08-30)

Features Added

• Added a new API, list_blob_names, to ContainerClient that lists only the names of the blobs in the respective container. This API is significantly faster than the traditional list_blobs and can be used if only the blob names are desired. It does not return any additional properties or metadata for the blobs.

12.14.0b1 (2022-08-23)

This version and all future versions will require Python 3.7+. Python 3.6 is no longer supported.

Features Added

• Added support for AzureNamedKeyCredential as a valid credential type.
• Added standard read method to StorageStreamDownloader.
• Added support for async streams (classes with an async read method) to async upload_blob.

Bugs Fixed

• Removed dead retry meachism from async azure.storage.blob.aio.StorageStreamDownloader.
• Updated exception catching of azure.storage.blob.StorageStreamDownloader's retry mechanism.
• Adjusted type hints for upload_blob and StorageStreamDownloader.readall.
• Fixed a bug where uploading an empty blob via upload_blob would fail with validate_content=True.

12.13.1 (2022-08-04)

Bugs Fixed

• Fixed two rare issues with ranged blob download when using client-side encryption V1 or V2.

12.13.0 (2022-07-07)

Bugs Fixed

• Stable release of features from 12.13.0b1.
• Added support for deleting versions in delete_blobs by supplying version_id.

12.13.0b1 (2022-06-15)

Features Added

• Added support for service version 2021-08-06.
• Added a new version of client-side encryption for blobs (version 2.0) which utilizes AES-GCM-256 encryption. If you are currently using client-side encryption, it is highly recommended to switch to a form of server-side encryption (Customer-Provided Key, Encryption Scope, etc.) or version 2.0 of client-side encryption. The encryption version can be specified on any client constructor via the encryption_version keyword (encryption_version='2.0').

12.12.0 (2022-05-09)

Features Added

• Stable release of features from 12.12.0b1.
• Added support for progress tracking to upload_blob() and download_blob() via a new optional callback,progress_hook.

Bugs Fixed

• Fixed a bug in BlobClient.from_blob_url() such that users will receive a more helpful error message if they pass an incorrect URL without a full /container/blob path.
• Fixed a bug, introduced in the previous beta release, that caused Authentication errors when attempting to use an Account SAS with certain service level operations.

12.12.0b1 (2022-04-14)

Features Added

• Added support for service version 2021-06-08.
• Added a new paginated method for listing page ranges, list_page_ranges(). This replaces get_page_ranges() which has been deprecated.
• Added support for copying source blob tags with start_copy_from_url() by specifying "COPY" for the tags keyword.

12.11.0 (2022-03-29)

Warning This release involves a bug fix that may change the behavior for some users. In previous versions, the tag parameter onBlobSasPermissions defaulted to True meaning a Blob SAS URL would include the t permission by default. This was not the intended behavior. This release adjusts BlobSasPermission so the tag permission will default to False, like all other permissions.

Bugs Fixed

• Fixed a bug in BlobSasPermissions where the tag permission had a default value of True and therefore was being added to the SAS token by default.

12.10.0 (2022-03-08)

This version and all future versions will require Python 3.6+. Python 2.7 is no longer supported.

Stable release of preview features

• Added support for service version 2021-02-12, 2021-04-10.
• Account level SAS tokens now supports two new permissions:
  • permanent_delete
  • set_immutability_policy
• Encryption Scope is now supported for Sync Blob Copy (copy_from_url()).
• Encryption Scope is now supported as a SAS permission.
• Added support for blob names containing invalid XML characters. Previously \uFFFE and \uFFFF would fail if present in blob name.
• Added support for listing system containers with get_blob_containers().
• Added support for find_blobs_by_tags() on a container.
• Added support for Find (f) container SAS permission.

Bugs Fixed

• Added all missing Service SAS permissions.
• Fixed a bug that prevented upload_blob() from working with an OS pipe reader stream on Linux. (#23131)

12.10.0b4 (2022-02-24)

Features Added

• Updated clients to support both SAS and OAuth together.
• Updated OAuth implementation to use the AAD scope returned in a Bearer challenge.

Bugs Fixed

• Addressed a few mypy typing hint errors.

12.10.0b3 (2022-02-08)

This version and all future versions will require Python 3.6+. Python 2.7 is no longer supported.

Features Added

• Added support for service version 2021-04-10.
• Added support for find_blobs_by_tags() on a container.
• Added support for Find (f) container SAS permission.

Bugs Fixed

• Update azure-core dependency to avoid inconsistent dependencies from being installed.

12.10.0b2 (2021-12-13)

Features Added

• Added support for service version 2021-02-12
• Added support for blob names container invalid XML characters. Previously \uFFFE and \uFFFF would fail if present in blob name.
• Added support for listing system containers with get_blob_containers().

Bugs Fixed

• BlobPrefix for aio operations is now exposed to be imported, previously it was private.

12.10.0b1 (2021-11-08)

New Features

• Account level SAS tokens now support two new permissions:
  • permanent_delete
• Encryption Scope is now supported for Sync Blob Copy (copy_from_url())
• Encryption Scope is now supported as a SAS permission

Fixes

• Blob Client Typing annotation issues have been resolved, specifically invalid type inference issues (#19906)
• Duplicate type signature issue has been resolved (#19739)

12.9.0 (2021-09-15)

Stable release of preview features

• Added support for service version 2020-10-02 (STG78)
• Added support for object level immutability policy with versioning (Version Level WORM).
• Added support for listing deleted root blobs that have versions.
• Added OAuth support for sync copy blob source.

12.9.0b1 (2021-07-27)

New Features

• Added support for object level immutability policy with versioning (Version Level WORM).
• Added support for listing deleted root blobs that have versions.
• Added OAuth support for sync copy blob source.

Fixes

• Fixed a bug for get_block_list (#16314)
• Ensured that download fails if blob modified mid download
• Enabled exists() for CPK encrypted blobs (#18041)

Notes

• Deprecated new_name in for undelete container operation

12.8.1 (2021-04-20)

Fixes

• Fixed retry on large block upload
• Make AccountName, AccountKey etc. in conn_str case insensitive
• Fixed downloader.chunks() return chunks in different size (#9419, #15648)
• Enabled exists() for CPK encrypted blobs (#18041)
• Fixed the ability to upload from a generator (#17418)
• Fixed unclosed ThreadPoolExecutor (#8955)
• Fixed retries for blob download streams (#18164, #17974, #10572 (comment))
• Added chunk streaming docstrings and samples (#17149, #11009)
• Added retry for blob download (#17974, #10572)
• Fixed encryption algorithm hardcoded setting (#17835)

12.8.0 (2021-03-01)

Stable release of preview features

• Added ContainerClient.exists() method
• Added container SAS support for blob batch operations

Fixes

• Fixed delete_blob() method signature (#15891)
• Fixed Content-MD5 throwing when passed (#15919)

12.8.0b1 (2021-02-10)

New Features

• Added ContainerClient.exists() method
• Added container SAS support for blob batch operations

12.7.1 (2021-01-20)

Fixes

• Fixed msrest dependency issue (#16250)

12.7.0 (2021-01-13)

Stable release of preview features

• Added upload_blob_from_url api on BlobClient.
• Added support for leasing blob when get/set tags, listing all tags when find blobs by tags.
• Added support for AzureSasCredential to allow SAS rotation in long living clients.

Fixes

• Fixed url parsing for blob emulator/localhost (#15882)

12.7.0b1 (2020-12-07)

New features

• Added upload_blob_from_url api on BlobClient
• Added support for leasing blob when get/set tags, listing all tags when find blobs by tags.

12.6.0 (2020-11-10)

Stable release of preview features

• Preview feature ArrowDialect as output format of query_blob
• Preview feature undelete_container on BlobServiceClient.
• Preview feature Last Access Time.

Fixes

• Fixed the expired Authorization token problem during retry (#14701, #14067)
• Catch exceptions thrown by async download (#14319)

Notes

• Updated dependency azure-core from azure-core<2.0.0,>=1.6.0 to azure-core<2.0.0,>=1.9.0 to get continuation_token attr on AzureError.

12.6.0b1 (2020-10-02)

New features

• Added support for Arrow format (ArrowType) output serialization using quick_query().
• Added support for undeleting a container.
• Added support for LastAccessTime property on a blob, which could be the last time a blob was written or read.

12.5.0 (2020-09-10)

New features

• Added support for checking if a blob exists using the exists method (#13221).

Fixes

• Fixed source URLs special characters issue. Users can now have special characters in their source URLs for copy_blob_from_url, upload_blob_from_url etc (#13275).
• Fixed authorization header on asyncio requests containing url-encoded-able characters (#11028).
• Fixed SAS credentials URL malformation when using local Azurite container (#11941).
• Fixed issue with permission string causing an authentication failure (#13099).
• Support for returning snapshot value in get_blob_properties response (#13287).

12.4.0 (2020-08-12)

New features

• Added support for Object Replication Service on list_blobs and get_blob_properties.
• Added more support for blob tags. Added if_tags_match_condition that allow a user to specify a SQL statement for the blob's tags to satisfy.
• Added support for setting and getting the default_index_document_path of StaticWebsite property on the service client.
• Added rehydrate_priority to BlobProperties.
• Added support to seal an append blob. Added test_seal_append_blob. Added ability to specify seal_destination_blob on start_copy_from_url. is_append_blob_sealed property returned on get_blob_properties/download_blob/list_blobs.
• Added support to set tier on a snapshot or version.

Fixes

• Fixed the bug when parsing blob url with '/' in blob name (#12563, #12568).
• Support batch delete empty blob list (#12778, #12779).
• Fixed blob_samples_query bug.
• Fixed empty etag in acquire_blob response (#8490).

12.4.0b1 (2020-07-07)

New features

• Added query_blob API to enable users to select/project on block blob or block blob snapshot data by providing simple query expressions.
• Added blob versioning feature, so that every time there is a blob override the version_id will be updated automatically and returned in the response, the version_id could be used later to refer to the overwritten blob.
• Added set_blob_tags,get_blob_tags and find_blobs_by_tags so that user can get blobs based on blob tags.
• Block size is increased to 4GB at maximum, max single put size is increased to 5GB.
• For replication enabled account, users can get replication policies when get blob properties.

12.3.2

Fixes

• Fixed issue where batch requests could not be combined with SAS (#9534)
• Batch requests now support applying parameters to individual blobs within the request via passing in a dictionary.
• Metadata cannot have leading space (#11457)
• Improve the performance of upload when using max_concurrency

Notes

• Updated dependency from azure-core<2.0.0,>=1.2.2 to azure-core<2.0.0,>=1.6.0

12.3.1 (2020-04-29)

Fixes

• Fixed issue where batch requests could not be combined with token credentials (#9534)
• Skip '/' in url encoding.

12.3.0 (2020-03-10)

New features

• stage_block now propagates the response from the service.

Fixes

• Fixed a bug where a new transport is being passed in the get_blob_client method instead of using the existing one in the ContainerClient.

Notes

• The StorageUserAgentPolicy is now replaced with the UserAgentPolicy from azure-core. With this, the custom user agents are now added as a prefix instead of being appended.

12.2.0

New features

• Added support for the 2019-07-07 service version, and added api_version parameter to clients.
• Added support for encryption scopes that that could be used to encrypt blob content.
• Added get_page_range_diff_for_managed_disk API which returns the list of valid page ranges diff between a snapshot and managed disk or another snapshot.

Fixes

• Responses are always decoded as UTF8

12.1.0 (2019-12-04)

New features

• Added download_blob method to the container_client.
• All the clients now have a close() method to close the sockets opened by the client when using without a context manager.

Fixes and improvements

• Fixes a bug where determining length breaks while uploading a blob when provided with an invalid fileno.
• Fix metadata not being included in commit_block_list operation.

12.0.0 (2019-10-31)

Breaking changes

• set_container_access_policy has required parameter signed_identifiers.
• NoRetry policy has been removed. Use keyword argument retry_total=0 for no retries.
• StorageStreamDownloader is no longer iterable. To iterate over the blob data stream, use StorageStreamDownloader.chunks.
• The public attributes of StorageStreamDownloader have been limited to:
  • name (str): The name of the blob.
  • container (str): The container the blob is being downloaded from.
  • properties (BlobProperties): The properties of the blob.
  • size (int): The size of the download. Either the total blob size, or the length of a subsection if sepcified. Previously called download_size.
• StorageStreamDownloader now has new functions:
  • readall(): Reads the complete download stream, returning bytes. This replaces the functions content_as_bytes and content_as_text which have been deprecated.
  • readinto(stream): Download the complete stream into the supplied writable stream, returning the number of bytes written. This replaces the function download_to_stream which has been deprecated.
• Module level functions upload_blob_to_url and download_blob_from_url functions options are now keyword only:
  • overwrite
  • max_concurrency
  • encoding
• Removed types that were accidentally exposed from two modules. Only BlobServiceClient, ContainerClient, BlobClient and BlobLeaseClient should be imported from azure.storage.blob.aio
• Logging has been renamed to BlobAnalyticsLogging.
• Client and model files have been made internal. Users should import from the top level modules azure.storage.blob and azure.storage.blob.aio only.
• All operations that take Etag conditional parameters (if_match and if_none_match) now take explicit etag and match_condition parameters, where etag is the Etag value, and match_condition is an instance of azure.core.MatchConditions.
• The generate_shared_access_signature methods on each of BlobServiceClient, ContainerClient and BlobClient have been replaced by module level functions generate_account_sas, generate_container_sas and generate_blob_sas.
• The batch APIs now have an additional keyword only argument raise_on_any_failure which defaults to True. This will raise an error even if there's a partial batch failure.
• LeaseClient has been renamed to BlobLeaseClient.
• get_service_stats now returns a dict
• get_service_properties now returns a dict with keys consistent to set_service_properties

New features

• Added async module-level upload_blob_to_url and download_blob_from_url functions.
• ResourceTypes, and Services now have method from_string which takes parameters as a string.

12.0.0b4 (2019-10-08)

Breaking changes

• Permission models.
  • AccountPermissions, BlobPermissions and ContainerPermissions have been renamed to AccountSasPermissions, BlobSasPermissions and ContainerSasPermissions respectively.
  • enum-like list parameters have been removed from all three of them.
  • __add__ and __or__ methods are removed.
• max_connections is now renamed to max_concurrency.
• ContainerClient now accepts only account_url with a mandatory string param container_name. To use a container_url, the method from_container_url must be used.
• BlobClient now accepts only account_url with mandatory string params container_name and blob_name. To use a blob_url, the method from_blob_url must be used.
• Some parameters have become keyword only, rather than positional. Some examples include:
  • loop
  • max_concurrency
  • validate_content
  • timeout etc.
• APIs now take in offset and length instead of range_start and range_end consistently. length is the number of bytes to take in starting from the offset. The APIs that have been changed include:
  • get_page_ranges
  • upload_page
  • upload_pages_from_url
  • clear_page
  • append_block_from_url
• block_id is not optional in BlobBlock model.

New features

• Add support for delete_blobs API to ContainerClient (Python 3 only)
• Add support for set_standard_blob_tier_blobs to ContainerClient (Python 3 only)
• Add support for set_premium_page_blob_tier_blobs to ContainerClient (Python 3 only)
• Added support to set rehydrate blob priority for Block Blob, including Set Standard Blob Tier/Copy Blob APIs
• Added blob tier support for Block Blob, including Upload Blob/Commit Block List/Copy Blob APIs.
• AccountSasPermissions, BlobSasPermissions, ContainerSasPermissions now have method from_string which takes parameters as a string.

Fixes and improvements

• Downloading page blobs now take advantage of their sparseness.
• The length param in download_blob now takes the number of bytes to take in starting from the offset instead of a harde set end value.

Dependency updates

• Adopted azure-core 1.0.0b4

  • If you later want to revert to previous versions of azure-storage-blob, or another Azure SDK library requiring azure-core 1.0.0b1 or azure-core 1.0.0b2, you must explicitly install the specific version of azure-core as well. For example:

  pip install azure-core==1.0.0b2 azure-storage-blob==12.0.0b2

12.0.0b3 (2019-09-10)

New features

• Added SAS support for snapshot and identity.
• Distributed tracing framework OpenCensus is now supported.
• Added support for append_block_from_url API for append blobs.
• Added support for upload_pages_from_url API for page blobs.
• Added support for client provided encryption key to numerous APIs.

Dependency updates

• Adopted azure-core 1.0.0b3

  • If you later want to revert to previous versions of azure-storage-blob, or another Azure SDK library requiring azure-core 1.0.0b1 or azure-core 1.0.0b2, you must explicitly install the specific version of azure-core as well. For example:

  pip install azure-core==1.0.0b2 azure-storage-blob==12.0.0b2

Fixes and improvements

• Fix where content-type was being added in the request when not mentioned explicitly.

12.0.0b2 (2019-08-06)

Breaking changes

• Renamed copy_blob_from_url to start_copy_from_url and changed behaviour to return a dictionary of copy properties rather than a polling object. Status of the copy operation can be retrieved with the get_blob_properties operation.
• Added abort_copy operation to the BlobClient class. This replaces the previous abort operation on the copy status polling operation.
• The behavior of listing operations has been modified:
  • The previous marker parameter has been removed.
  • The iterable response object now supports a by_page function that will return a secondary iterator of batches of results. This function supports a continuation_token parameter to replace the previous marker parameter.
• Some parameters have become keyword only, rather than positional. Some examples include:
  • timeout
  • lease
  • encoding
  • Modification conditions, e.g. if_modified_since, if_match , maxsize_condition, etc

New features

• Added async APIs to subnamespace azure.storage.blob.aio.
• Distributed tracing framework OpenCensus is now supported.

Dependency updates

• Adopted azure-core 1.0.0b2

  • If you later want to revert to azure-storage-blob 12.0.0b1, or another Azure SDK library requiring azure-core 1.0.0b1, you must explicitly install azure-core 1.0.0b1 as well. For example:

  pip install azure-core==1.0.0b1 azure-storage-blob==12.0.0b1

Fixes and improvements

• Fix for SAS URL encoding (#6500)
• General refactor of duplicate and shared code.

12.0.0b1 (2019-07-02)

Version 12.0.0b1 is the first preview of our efforts to create a user-friendly and Pythonic client library for Azure Storage Blobs. For more information about this, and preview releases of other Azure SDK libraries, please visit https://aka.ms/azure-sdk-preview1-python.

Breaking changes: New API design

• Operations are now scoped to a particular client:

  • BlobServiceClient: This client handles account-level operations. This includes managing service properties and listing the containers within an account.
  • ContainerClient: The client handles operations for a particular container. This includes creating or deleting that container, as well as listing the blobs within that container and managing properties and metadata.
  • BlobClient: The client handles operations for a particular blob. This includes creating or deleting that blob, as well as upload and download data and managing properties. This BlobClient handles all blob types (block, page and append). Where operations can behave differently according to type (i.e. upload_blob) the default behaviour will be block blobs unless otherwise specified.
  • LeaseClient: Handles all lease operations for both containers and blobs.

  These clients can be accessed by navigating down the client hierarchy, or instantiated directly using URLs to the resource (account, container or blob). For full details on the new API, please see the reference documentation.

• Copy blob operations now return a polling object that can be used to check the status of the operation, as well as abort the operation.

• New module level operations for simple upload and download using a blob URL.

• Download operations now return a streaming object that can download data in multiple ways:

  • Iteration: The streamer is an iterable object that will download and yield the content in chunks. Only supports single threaded download.
  • content_as_bytes: Return the entire blob content as bytes. Blocking operation that supports multi-threaded download.
  • content_as_text: Return the entire blob content as decoded text. Blocking operation that supports multi-threaded download.
  • download_to_stream: Download the entire content to an open stream handle (e.g. an open file). Supports multi-threaded download.

• New underlying REST pipeline implementation, based on the new azure-core library.

• Client and pipeline configuration is now available via keyword arguments at both the client level, and per-operation. See reference documentation for a full list of optional configuration arguments.

• Authentication using azure-identity credentials

  • see the Azure Identity documentation for more information

• New error hierarchy:

  • All service errors will now use the base type: azure.core.exceptions.HttpResponseError
  • The are a couple of specific exception types derived from this base type for common error scenarios:
    • ResourceNotFoundError: The resource (e.g. queue, message) could not be found. Commonly a 404 status code.
    • ResourceExistsError: A resource conflict - commonly caused when attempting to create a resource that already exists.
    • ResourceModifiedError: The resource has been modified (e.g. overwritten) and therefore the current operation is in conflict. Alternatively this may be raised if a condition on the operation is not met.
    • ClientAuthenticationError: Authentication failed.

• Operation set_blob_properties has been renamed to set_http_headers.

• Operations get_blob_to_<output> have been replaced with download_blob. See above for download output options.

• Operations create_blob_from_<input> have been replace with upload_blob.

• Operation create_blob has been renamed to separate create_page_blob and create_append_blob.

• Operations get_container_acl and set_container_acl have been renamed to get_container_access_policy and set_container_access_policy.

• Operation snapshot_blob has been renamed to create_snapshot.

• Operation copy_blob has been renamed to copy_blob_from_url.

• Operations put_block and put_block_from_url have been renamed to stage_block and stage_block_from_url.

• Operation put_block_list has been renamed to commit_block_list.

• No longer have specific operations for get_metadata - use get_properties instead.

• No longer have specific operations for exists - use get_properties instead.

• Operation incremental_copy_blob has been replaced by an optional boolean flag in the copy_blob_from_url operation.

• Operation update_page has been renamed to upload_page.

• Operation get_page_ranges_diff has been replaced by an optional str flag in the get_page_ranges operation.

2.0.1

• Updated dependency on azure-storage-common.

2.0.0

• Support for 2018-11-09 REST version. Please see our REST API documentation and blog for information about the related added features.
• Added support for append block from URL(synchronously) for append blobs.
• Added support for update page from URL(synchronously) for page blobs.
• Added support for generating and using blob snapshot SAS tokens.
• Added support for generating user delegation SAS tokens.

1.5.0

• Added new method list_blob_names to efficiently list only blob names in an efficient way.

1.4.0

• azure-storage-nspkg is not installed anymore on Python 3 (PEP420-based namespace package)
• copy_blob method added to BlockBlobService to enable support for deep sync copy.

1.3.1

• Fixed design flaw where get_blob_to_* methods buffer entire blob when max_connections is set to 1.
• Added support for access conditions on append_blob_from_* methods.

1.3.0

• Support for 2018-03-28 REST version. Please see our REST API documentation and blog for information about the related added features.
• Added support for setting static website service properties.
• Added support for getting account information, such as SKU name and account kind.
• Added support for put block from URL(synchronously).

1.2.0rc1

• Support for 2017-11-09 REST version. Please see our REST API documentation and blog for information about the related added features.
• Support for write-once read-many containers.
• Added support for OAuth authentication for HTTPS requests(Please note that this feature is available in preview).

1.1.0

• Support for 2017-07-29 REST version. Please see our REST API documentation and blogs for information about the related added features.
• Added support for soft delete feature. If a delete retention policy is enabled through the set service properties API, then blobs or snapshots could be deleted softly and retained for a specified number of days, before being permanently removed by garbage collection.
• Error message now contains the ErrorCode from the x-ms-error-code header value.

1.0.0

• The package has switched from Apache 2.0 to the MIT license.
• Fixed bug where get_blob_to_* cannot get a single byte when start_range and end_range are both equal to 0.
• Optimized page blob upload for create_blob_from_* methods, by skipping the empty chunks.
• Added convenient method to generate container url (make_container_url).
• Metadata keys are now case-preserving when fetched from the service. Previously they were made lower-case by the library.

0.37.1

• Enabling MD5 validation no longer uses the memory-efficient algorithm for large block blobs, since computing the MD5 hash requires reading the entire block into memory.
• Fixed a bug in the _SubStream class which was at risk of causing data corruption when using the memory-efficient algorithm for large block blobs.
• Support for AccessTierChangeTime to get the last time a tier was modified on an individual blob.