BlockBlobService class

Definition

Block blobs let you upload large blobs efficiently. Block blobs are comprised of blocks, each of which is identified by a block ID. You create or modify a block blob by writing a set of blocks and committing them by their block IDs. Each block can be a different size, up to a maximum of 100 MB, and a block blob can include up to 50,000 blocks. The maximum size of a block blob is therefore approximately 4.75 TB (100 MB X 50,000 blocks). If you are writing a block blob that is no more than 64 MB in size, you can upload it in its entirety with a single write operation; see create_blob_from_bytes.

BlockBlobService(account_name=None, account_key=None, sas_token=None, is_emulated=False, protocol='https', endpoint_suffix='core.windows.net', custom_domain=None, request_session=None, connection_string=None, socket_timeout=None, token_credential=None)
Inheritance
azure.storage.common.storageclient.StorageClient
BlockBlobService

Variables

MAX_SINGLE_PUT_SIZE
int
The largest size upload supported in a single put call. This is used by the create_blob_from_* methods if the content length is known and is less than this value.
MAX_BLOCK_SIZE
int
The size of the blocks put by create_blob_from_* methods if the content length is unknown or is larger than MAX_SINGLE_PUT_SIZE. Smaller blocks may be put. The maximum block size the service supports is 100MB.
MIN_LARGE_BLOCK_UPLOAD_THRESHOLD
int
The minimum block size at which the the memory-optimized, block upload algorithm is considered. This algorithm is only applicable to the create_blob_from_file and create_blob_from_stream methods and will prevent the full buffering of blocks. In addition to the block size, ContentMD5 validation and Encryption must be disabled as these options require the blocks to be buffered.

Methods

copy_blob(container_name, blob_name, copy_source, metadata=None, source_if_modified_since=None, source_if_unmodified_since=None, source_if_match=None, source_if_none_match=None, destination_if_modified_since=None, destination_if_unmodified_since=None, destination_if_match=None, destination_if_none_match=None, destination_lease_id=None, source_lease_id=None, timeout=None, requires_sync=None)

Copies a blob. This operation returns a copy operation properties object. The copy operation may be configured to either be an asynchronous, best-effort operation, or a synchronous operation.

The source must be a block blob if requires_sync is true. Any existing destination blob will be overwritten. The destination blob cannot be modified while a copy operation is in progress.

When copying from a block blob, all committed blocks and their block IDs are copied. Uncommitted blocks are not copied. At the end of the copy operation, the destination blob will have the same committed block count as the source.

You can call get_blob_properties on the destination blob to check the status of the copy operation. The final blob will be committed when the copy completes.

Name of the destination container. The container must exist. :param str blob_name: Name of the destination blob. If the destination blob exists, it will be overwritten. Otherwise, it will be created. :param str copy_source: A URL of up to 2 KB in length that specifies an Azure file or blob. The value should be URL-encoded as it would appear in a request URI. If the source is in another account, the source must either be public or must be authenticated via a shared access signature. If the source is public, no authentication is required. Examples: https://myaccount.blob.core.windows.net/mycontainer/myblob https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot= https://otheraccount.blob.core.windows.net/mycontainer/myblob?sastoken :param metadata: Name-value pairs associated with the blob as metadata. If no name-value pairs are specified, the operation will copy the metadata from the source blob or file to the destination blob. If one or more name-value pairs are specified, the destination blob is created with the specified metadata, and metadata is not copied from the source blob or file. :type metadata: dict(str, str) :param datetime source_if_modified_since: A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this conditional header to copy the blob only if the source blob has been modified since the specified date/time. :param datetime source_if_unmodified_since: A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this conditional header to copy the blob only if the source blob has not been modified since the specified date/time. :param ETag source_if_match: An ETag value, or the wildcard character (). Specify this conditional header to copy the source blob only if its ETag matches the value specified. If the ETag values do not match, the Blob service returns status code 412 (Precondition Failed). This header cannot be specified if the source is an Azure File. :param ETag source_if_none_match: An ETag value, or the wildcard character (). Specify this conditional header to copy the blob only if its ETag does not match the value specified. If the values are identical, the Blob service returns status code 412 (Precondition Failed). This header cannot be specified if the source is an Azure File. :param datetime destination_if_modified_since: A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this conditional header to copy the blob only if the destination blob has been modified since the specified date/time. If the destination blob has not been modified, the Blob service returns status code 412 (Precondition Failed). :param datetime destination_if_unmodified_since: A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this conditional header to copy the blob only if the destination blob has not been modified since the specified date/time. If the destination blob has been modified, the Blob service returns status code 412 (Precondition Failed). :param ETag destination_if_match: An ETag value, or the wildcard character (). Specify an ETag value for this conditional header to copy the blob only if the specified ETag value matches the ETag value for an existing destination blob. If the ETag for the destination blob does not match the ETag specified for If-Match, the Blob service returns status code 412 (Precondition Failed). :param ETag destination_if_none_match: An ETag value, or the wildcard character (). Specify an ETag value for this conditional header to copy the blob only if the specified ETag value does not match the ETag value for the destination blob. Specify the wildcard character (*) to perform the operation only if the destination blob does not exist. If the specified condition isn't met, the Blob service returns status code 412 (Precondition Failed). :param str destination_lease_id: The lease ID specified for this header must match the lease ID of the destination blob. If the request does not include the lease ID or it is not valid, the operation fails with status code 412 (Precondition Failed). :param str source_lease_id: Specify this to perform the Copy Blob operation only if the lease ID given matches the active lease ID of the source blob. :param int timeout: The timeout parameter is expressed in seconds. :param bool requires_sync: Enforces that the service will not return a response until the copy is complete. :return: Copy operation properties such as status, source, and ID. :rtype: CopyProperties

create_blob_from_bytes(container_name, blob_name, blob, index=0, count=None, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None)

Creates a new blob from an array of bytes, or updates the content of an existing blob, with automatic chunking and progress notifications.

create_blob_from_path(container_name, blob_name, file_path, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None)

Creates a new blob from a file path, or updates the content of an existing blob, with automatic chunking and progress notifications.

create_blob_from_stream(container_name, blob_name, stream, count=None, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None, use_byte_buffer=False)

Creates a new blob from a file/stream, or updates the content of an existing blob, with automatic chunking and progress notifications.

create_blob_from_text(container_name, blob_name, text, encoding='utf-8', content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None)

Creates a new blob from str/unicode, or updates the content of an existing blob, with automatic chunking and progress notifications.

get_block_list(container_name, blob_name, snapshot=None, block_list_type=None, lease_id=None, timeout=None)

Retrieves the list of blocks that have been uploaded as part of a block blob. There are two block lists maintained for a blob:

Committed Block List: The list of blocks that have been successfully committed to a given blob with Put Block List.

Uncommitted Block List: The list of blocks that have been uploaded for a blob using Put Block, but that have not yet been committed. These blocks are stored in Azure in association with a blob, but do not yet form part of the blob.

put_block(container_name, blob_name, block, block_id, validate_content=False, lease_id=None, timeout=None)

Creates a new block to be committed as part of a blob.

put_block_from_url(container_name, blob_name, copy_source_url, source_range_start, source_range_end, block_id, source_content_md5=None, lease_id=None, timeout=None)

Creates a new block to be committed as part of a blob.

put_block_list(container_name, blob_name, block_list, content_settings=None, metadata=None, validate_content=False, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None)

Writes a blob by specifying the list of block IDs that make up the blob. In order to be written as part of a blob, a block must have been successfully written to the server in a prior Put Block operation.

You can call Put Block List to update a blob by uploading only those blocks that have changed, then committing the new and existing blocks together. You can do this by specifying whether to commit a block from the committed block list or from the uncommitted block list, or to commit the most recently uploaded version of the block, whichever list it may belong to.

set_standard_blob_tier(container_name, blob_name, standard_blob_tier, timeout=None)

Sets the block blob tiers on the blob. This API is only supported for block blobs on standard storage accounts.

copy_blob(container_name, blob_name, copy_source, metadata=None, source_if_modified_since=None, source_if_unmodified_since=None, source_if_match=None, source_if_none_match=None, destination_if_modified_since=None, destination_if_unmodified_since=None, destination_if_match=None, destination_if_none_match=None, destination_lease_id=None, source_lease_id=None, timeout=None, requires_sync=None)

Copies a blob. This operation returns a copy operation properties object. The copy operation may be configured to either be an asynchronous, best-effort operation, or a synchronous operation.

The source must be a block blob if requires_sync is true. Any existing destination blob will be overwritten. The destination blob cannot be modified while a copy operation is in progress.

When copying from a block blob, all committed blocks and their block IDs are copied. Uncommitted blocks are not copied. At the end of the copy operation, the destination blob will have the same committed block count as the source.

You can call get_blob_properties on the destination blob to check the status of the copy operation. The final blob will be committed when the copy completes.

Name of the destination container. The container must exist. :param str blob_name: Name of the destination blob. If the destination blob exists, it will be overwritten. Otherwise, it will be created. :param str copy_source: A URL of up to 2 KB in length that specifies an Azure file or blob. The value should be URL-encoded as it would appear in a request URI. If the source is in another account, the source must either be public or must be authenticated via a shared access signature. If the source is public, no authentication is required. Examples: https://myaccount.blob.core.windows.net/mycontainer/myblob https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot= https://otheraccount.blob.core.windows.net/mycontainer/myblob?sastoken :param metadata: Name-value pairs associated with the blob as metadata. If no name-value pairs are specified, the operation will copy the metadata from the source blob or file to the destination blob. If one or more name-value pairs are specified, the destination blob is created with the specified metadata, and metadata is not copied from the source blob or file. :type metadata: dict(str, str) :param datetime source_if_modified_since: A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this conditional header to copy the blob only if the source blob has been modified since the specified date/time. :param datetime source_if_unmodified_since: A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this conditional header to copy the blob only if the source blob has not been modified since the specified date/time. :param ETag source_if_match: An ETag value, or the wildcard character (). Specify this conditional header to copy the source blob only if its ETag matches the value specified. If the ETag values do not match, the Blob service returns status code 412 (Precondition Failed). This header cannot be specified if the source is an Azure File. :param ETag source_if_none_match: An ETag value, or the wildcard character (). Specify this conditional header to copy the blob only if its ETag does not match the value specified. If the values are identical, the Blob service returns status code 412 (Precondition Failed). This header cannot be specified if the source is an Azure File. :param datetime destination_if_modified_since: A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this conditional header to copy the blob only if the destination blob has been modified since the specified date/time. If the destination blob has not been modified, the Blob service returns status code 412 (Precondition Failed). :param datetime destination_if_unmodified_since: A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this conditional header to copy the blob only if the destination blob has not been modified since the specified date/time. If the destination blob has been modified, the Blob service returns status code 412 (Precondition Failed). :param ETag destination_if_match: An ETag value, or the wildcard character (). Specify an ETag value for this conditional header to copy the blob only if the specified ETag value matches the ETag value for an existing destination blob. If the ETag for the destination blob does not match the ETag specified for If-Match, the Blob service returns status code 412 (Precondition Failed). :param ETag destination_if_none_match: An ETag value, or the wildcard character (). Specify an ETag value for this conditional header to copy the blob only if the specified ETag value does not match the ETag value for the destination blob. Specify the wildcard character (*) to perform the operation only if the destination blob does not exist. If the specified condition isn't met, the Blob service returns status code 412 (Precondition Failed). :param str destination_lease_id: The lease ID specified for this header must match the lease ID of the destination blob. If the request does not include the lease ID or it is not valid, the operation fails with status code 412 (Precondition Failed). :param str source_lease_id: Specify this to perform the Copy Blob operation only if the lease ID given matches the active lease ID of the source blob. :param int timeout: The timeout parameter is expressed in seconds. :param bool requires_sync: Enforces that the service will not return a response until the copy is complete. :return: Copy operation properties such as status, source, and ID. :rtype: CopyProperties

copy_blob(container_name, blob_name, copy_source, metadata=None, source_if_modified_since=None, source_if_unmodified_since=None, source_if_match=None, source_if_none_match=None, destination_if_modified_since=None, destination_if_unmodified_since=None, destination_if_match=None, destination_if_none_match=None, destination_lease_id=None, source_lease_id=None, timeout=None, requires_sync=None)

Parameters

container_name
str
blob_name
copy_source
metadata
default value: None
source_if_modified_since
default value: None
source_if_unmodified_since
default value: None
source_if_match
default value: None
source_if_none_match
default value: None
destination_if_modified_since
default value: None
destination_if_unmodified_since
default value: None
destination_if_match
default value: None
destination_if_none_match
default value: None
destination_lease_id
default value: None
source_lease_id
default value: None
timeout
default value: None
requires_sync
default value: None

create_blob_from_bytes(container_name, blob_name, blob, index=0, count=None, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None)

Creates a new blob from an array of bytes, or updates the content of an existing blob, with automatic chunking and progress notifications.

create_blob_from_bytes(container_name, blob_name, blob, index=0, count=None, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None)

Parameters

container_name
str

Name of existing container.

blob_name
str

Name of blob to create or update.

blob
bytes

Content of blob as an array of bytes.

index
int

Start index in the array of bytes.

default value: 0
count
int

Number of bytes to upload. Set to None or negative value to upload all bytes starting from index.

default value: None
content_settings
ContentSettings

ContentSettings object used to set blob properties.

default value: None
metadata
dict(str, str)

Name-value pairs associated with the blob as metadata.

default value: None
validate_content
bool

If true, calculates an MD5 hash for each chunk of the blob. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the blob.

default value: False
progress_callback
func(current, total)

Callback for progress with signature function(current, total) where current is the number of bytes transfered so far, and total is the size of the blob, or None if the total size is unknown.

default value: None
max_connections
int

Maximum number of parallel connections to use when the blob size exceeds 64MB.

default value: 2
lease_id
str

Required if the blob has an active lease.

default value: None
if_modified_since
datetime

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

default value: None
if_unmodified_since
datetime

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

default value: None
if_match
str

An ETag value, or the wildcard character (*). Specify this header to perform the operation only if the resource's ETag matches the value specified.

default value: None
if_none_match
str

An ETag value, or the wildcard character (). Specify this header to perform the operation only if the resource's ETag does not match the value specified. Specify the wildcard character () to perform the operation only if the resource does not exist, and fail the operation if it does exist.

default value: None
timeout
int

The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually.

default value: None

Returns

ETag and last modified properties for the Block Blob

Return type

create_blob_from_path(container_name, blob_name, file_path, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None)

Creates a new blob from a file path, or updates the content of an existing blob, with automatic chunking and progress notifications.

create_blob_from_path(container_name, blob_name, file_path, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None)

Parameters

container_name
str

Name of existing container.

blob_name
str

Name of blob to create or update.

file_path
str

Path of the file to upload as the blob content.

content_settings
ContentSettings

ContentSettings object used to set blob properties.

default value: None
metadata
dict(str, str)

Name-value pairs associated with the blob as metadata.

default value: None
validate_content
bool

If true, calculates an MD5 hash for each chunk of the blob. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the blob. Also note that if enabled, the memory-efficient upload algorithm will not be used, because computing the MD5 hash requires buffering entire blocks, and doing so defeats the purpose of the memory-efficient algorithm.

default value: False
progress_callback
func(current, total)

Callback for progress with signature function(current, total) where current is the number of bytes transfered so far, and total is the size of the blob, or None if the total size is unknown.

default value: None
max_connections
int

Maximum number of parallel connections to use when the blob size exceeds 64MB.

default value: 2
lease_id
str

Required if the blob has an active lease.

default value: None
if_modified_since
datetime

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

default value: None
if_unmodified_since
datetime

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

default value: None
if_match
str

An ETag value, or the wildcard character (*). Specify this header to perform the operation only if the resource's ETag matches the value specified.

default value: None
if_none_match
str

An ETag value, or the wildcard character (). Specify this header to perform the operation only if the resource's ETag does not match the value specified. Specify the wildcard character () to perform the operation only if the resource does not exist, and fail the operation if it does exist.

default value: None
timeout
int

The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually.

default value: None

Returns

ETag and last modified properties for the Block Blob

Return type

create_blob_from_stream(container_name, blob_name, stream, count=None, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None, use_byte_buffer=False)

Creates a new blob from a file/stream, or updates the content of an existing blob, with automatic chunking and progress notifications.

create_blob_from_stream(container_name, blob_name, stream, count=None, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None, use_byte_buffer=False)

Parameters

container_name
str

Name of existing container.

blob_name
str

Name of blob to create or update.

stream
IOBase

Opened file/stream to upload as the blob content.

count
int

Number of bytes to read from the stream. This is optional, but should be supplied for optimal performance.

default value: None
content_settings
ContentSettings

ContentSettings object used to set blob properties.

default value: None
metadata
dict(str, str)

Name-value pairs associated with the blob as metadata.

default value: None
validate_content
bool

If true, calculates an MD5 hash for each chunk of the blob. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the blob. Also note that if enabled, the memory-efficient upload algorithm will not be used, because computing the MD5 hash requires buffering entire blocks, and doing so defeats the purpose of the memory-efficient algorithm.

default value: False
progress_callback
func(current, total)

Callback for progress with signature function(current, total) where current is the number of bytes transfered so far, and total is the size of the blob, or None if the total size is unknown.

default value: None
max_connections
int

Maximum number of parallel connections to use when the blob size exceeds 64MB. Note that parallel upload requires the stream to be seekable.

default value: 2
lease_id
str

Required if the blob has an active lease.

default value: None
if_modified_since
datetime

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

default value: None
if_unmodified_since
datetime

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

default value: None
if_match
str

An ETag value, or the wildcard character (*). Specify this header to perform the operation only if the resource's ETag matches the value specified.

default value: None
if_none_match
str

An ETag value, or the wildcard character (). Specify this header to perform the operation only if the resource's ETag does not match the value specified. Specify the wildcard character () to perform the operation only if the resource does not exist, and fail the operation if it does exist.

default value: None
timeout
int

The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually.

default value: None
use_byte_buffer
bool

If True, this will force usage of the original full block buffering upload path. By default, this value is False and will employ a memory-efficient, streaming upload algorithm under the following conditions: The provided stream is seekable, 'require_encryption' is False, and MAX_BLOCK_SIZE >= MIN_LARGE_BLOCK_UPLOAD_THRESHOLD. One should consider the drawbacks of using this approach. In order to achieve memory-efficiency, a IOBase stream or file-like object is segmented into logical blocks using a SubStream wrapper. In order to read the correct data, each SubStream must acquire a lock so that it can safely seek to the right position on the shared, underlying stream. If max_connections > 1, the concurrency will result in a considerable amount of seeking on the underlying stream. For the most common inputs such as a file-like stream object, seeking is an inexpensive operation and this is not much of a concern. However, for other variants of streams this may not be the case. The trade-off for memory-efficiency must be weighed against the cost of seeking with your input stream. The SubStream class will attempt to buffer up to 4 MB internally to reduce the amount of seek and read calls to the underlying stream. This is particularly beneficial when uploading larger blocks.

default value: False

Returns

ETag and last modified properties for the Block Blob

Return type

create_blob_from_text(container_name, blob_name, text, encoding='utf-8', content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None)

Creates a new blob from str/unicode, or updates the content of an existing blob, with automatic chunking and progress notifications.

create_blob_from_text(container_name, blob_name, text, encoding='utf-8', content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None)

Parameters

container_name
str

Name of existing container.

blob_name
str

Name of blob to create or update.

text
str

Text to upload to the blob.

encoding
str

Python encoding to use to convert the text to bytes.

default value: utf-8
content_settings
ContentSettings

ContentSettings object used to set blob properties.

default value: None
metadata
dict(str, str)

Name-value pairs associated with the blob as metadata.

default value: None
validate_content
bool

If true, calculates an MD5 hash for each chunk of the blob. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the blob.

default value: False
progress_callback
func(current, total)

Callback for progress with signature function(current, total) where current is the number of bytes transfered so far, and total is the size of the blob, or None if the total size is unknown.

default value: None
max_connections
int

Maximum number of parallel connections to use when the blob size exceeds 64MB.

default value: 2
lease_id
str

Required if the blob has an active lease.

default value: None
if_modified_since
datetime

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

default value: None
if_unmodified_since
datetime

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

default value: None
if_match
str

An ETag value, or the wildcard character (*). Specify this header to perform the operation only if the resource's ETag matches the value specified.

default value: None
if_none_match
str

An ETag value, or the wildcard character (). Specify this header to perform the operation only if the resource's ETag does not match the value specified. Specify the wildcard character () to perform the operation only if the resource does not exist, and fail the operation if it does exist.

default value: None
timeout
int

The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually.

default value: None

Returns

ETag and last modified properties for the Block Blob

Return type

get_block_list(container_name, blob_name, snapshot=None, block_list_type=None, lease_id=None, timeout=None)

Retrieves the list of blocks that have been uploaded as part of a block blob. There are two block lists maintained for a blob:

Committed Block List: The list of blocks that have been successfully committed to a given blob with Put Block List.

Uncommitted Block List: The list of blocks that have been uploaded for a blob using Put Block, but that have not yet been committed. These blocks are stored in Azure in association with a blob, but do not yet form part of the blob.

get_block_list(container_name, blob_name, snapshot=None, block_list_type=None, lease_id=None, timeout=None)

Parameters

container_name
str

Name of existing container.

blob_name
str

Name of existing blob.

snapshot
str

Datetime to determine the time to retrieve the blocks.

default value: None
block_list_type
str

Specifies whether to return the list of committed blocks, the list of uncommitted blocks, or both lists together. Valid values are: committed, uncommitted, or all.

default value: None
lease_id
str

Required if the blob has an active lease.

default value: None
timeout
int

The timeout parameter is expressed in seconds.

default value: None

Returns

list committed and/or uncommitted blocks for Block Blob

Return type

put_block(container_name, blob_name, block, block_id, validate_content=False, lease_id=None, timeout=None)

Creates a new block to be committed as part of a blob.

put_block(container_name, blob_name, block, block_id, validate_content=False, lease_id=None, timeout=None)

Parameters

container_name
str

Name of existing container.

blob_name
str

Name of blob.

block
IOBase or bytesContent of the block.

Content of the block.

block_id
str

A valid Base64 string value that identifies the block. Prior to encoding, the string must be less than or equal to 64 bytes in size. For a given blob, the length of the value specified for the blockid parameter must be the same size for each block. Note that the Base64 string must be URL-encoded.

validate_content
bool

If true, calculates an MD5 hash of the block content. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the blob.

default value: False
lease_id
str

Required if the blob has an active lease.

default value: None
timeout
int

The timeout parameter is expressed in seconds.

default value: None

put_block_from_url(container_name, blob_name, copy_source_url, source_range_start, source_range_end, block_id, source_content_md5=None, lease_id=None, timeout=None)

Creates a new block to be committed as part of a blob.

put_block_from_url(container_name, blob_name, copy_source_url, source_range_start, source_range_end, block_id, source_content_md5=None, lease_id=None, timeout=None)

Parameters

container_name
str

Name of existing container.

blob_name
str

Name of blob.

copy_source_url
str

The URL of the source data. It can point to any Azure Blob or File, that is either public or has a shared access signature attached.

source_range_start
int

This indicates the start of the range of bytes(inclusive) that has to be taken from the copy source.

source_range_end
int

This indicates the end of the range of bytes(inclusive) that has to be taken from the copy source.

block_id
str

A valid Base64 string value that identifies the block. Prior to encoding, the string must be less than or equal to 64 bytes in size. For a given blob, the length of the value specified for the blockid parameter must be the same size for each block. Note that the Base64 string must be URL-encoded.

source_content_md5
str

If given, the service will calculate the MD5 hash of the block content and compare against this value.

default value: None
lease_id
str

Required if the blob has an active lease.

default value: None
timeout
int

The timeout parameter is expressed in seconds.

default value: None

put_block_list(container_name, blob_name, block_list, content_settings=None, metadata=None, validate_content=False, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None)

Writes a blob by specifying the list of block IDs that make up the blob. In order to be written as part of a blob, a block must have been successfully written to the server in a prior Put Block operation.

You can call Put Block List to update a blob by uploading only those blocks that have changed, then committing the new and existing blocks together. You can do this by specifying whether to commit a block from the committed block list or from the uncommitted block list, or to commit the most recently uploaded version of the block, whichever list it may belong to.

put_block_list(container_name, blob_name, block_list, content_settings=None, metadata=None, validate_content=False, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None)

Parameters

container_name
str

Name of existing container.

blob_name
str

Name of existing blob.

block_list
list(BlobBlock)

A list of <xref:azure.storeage.blob.models.BlobBlock> containing the block ids and block state.

content_settings
ContentSettings

ContentSettings object used to set properties on the blob.

default value: None
metadata
dict(str, str)

Name-value pairs associated with the blob as metadata.

default value: None
validate_content
bool

If true, calculates an MD5 hash of the block list content. The storage service checks the hash of the block list content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this check is associated with the block list content, and not with the content of the blob itself.

default value: False
lease_id
str

Required if the blob has an active lease.

default value: None
if_modified_since
datetime

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

default value: None
if_unmodified_since
datetime

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

default value: None
if_match
str

An ETag value, or the wildcard character (*). Specify this header to perform the operation only if the resource's ETag matches the value specified.

default value: None
if_none_match
str

An ETag value, or the wildcard character (). Specify this header to perform the operation only if the resource's ETag does not match the value specified. Specify the wildcard character () to perform the operation only if the resource does not exist, and fail the operation if it does exist.

default value: None
timeout
int

The timeout parameter is expressed in seconds.

default value: None

Returns

ETag and last modified properties for the updated Block Blob

Return type

set_standard_blob_tier(container_name, blob_name, standard_blob_tier, timeout=None)

Sets the block blob tiers on the blob. This API is only supported for block blobs on standard storage accounts.

set_standard_blob_tier(container_name, blob_name, standard_blob_tier, timeout=None)

Parameters

container_name
str

Name of existing container.

blob_name
str

Name of blob to update.

standard_blob_tier
StandardBlobTier

A standard blob tier value to set the blob to. For this version of the library, this is only applicable to block blobs on standard storage accounts.

timeout
int

The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually.

default value: None

Attributes

MAX_BLOCK_SIZE

MAX_BLOCK_SIZE = 4194304

MAX_SINGLE_PUT_SIZE

MAX_SINGLE_PUT_SIZE = 67108864

MIN_LARGE_BLOCK_UPLOAD_THRESHOLD

MIN_LARGE_BLOCK_UPLOAD_THRESHOLD = 4194305