blob Package

Packages

aio

Classes

AccessPolicy	Access Policy class used by the set and get access policy methods in each service. A stored access policy can specify the start time, expiry time, and permissions for the Shared Access Signatures with which it's associated. Depending on how you want to control access to your resource, you can specify all of these parameters within the stored access policy, and omit them from the URL for the Shared Access Signature. Doing so permits you to modify the associated signature's behavior at any time, as well as to revoke it. Or you can specify one or more of the access policy parameters within the stored access policy, and the others on the URL. Finally, you can specify all of the parameters on the URL. In this case, you can use the stored access policy to revoke the signature, but not to modify its behavior. Together the Shared Access Signature and the stored access policy must include all fields required to authenticate the signature. If any required fields are missing, the request will fail. Likewise, if a field is specified both in the Shared Access Signature URL and in the stored access policy, the request will fail with status code 400 (Bad Request).
AccountSasPermissions	ResourceTypes class to be used with generate_account_sas function and for the AccessPolicies used with set_*_acl. There are two types of SAS which may be used to grant resource access. One is to grant access to a specific resource (resource-specific). Another is to grant access to the entire service for a specific account and allow certain operations based on perms found here.
ArrowDialect	field of an arrow schema. All required parameters must be populated in order to send to Azure.
BlobAnalyticsLogging	Azure Analytics Logging settings.
BlobBlock	BlockBlob Block class.
BlobClient	A client to interact with a specific blob, although that blob may not yet exist. For more optional configuration, please click here.
BlobLeaseClient	Creates a new BlobLeaseClient. This client provides lease operations on a BlobClient or ContainerClient. :param client: The client of the blob or container to lease. :type client: Union[BlobClient, ContainerClient] :param lease_id: A string representing the lease ID of an existing lease. This value does not need to be specified in order to acquire a new lease, or break one. :type lease_id: Optional[str]
BlobPrefix	An Iterable of Blob properties. Returned from walk_blobs when a delimiter is used. Can be thought of as a virtual blob directory.
BlobProperties	Blob Properties.
BlobQueryError	The error happened during quick query operation.
BlobQueryReader	A streaming object to read query results.
BlobSasPermissions	BlobSasPermissions class to be used with the generate_blob_sas function.
BlobServiceClient	A client to interact with the Blob Service at the account level. This client provides operations to retrieve and configure the account properties as well as list, create and delete containers within the account. For operations relating to a specific container or blob, clients for those entities can also be retrieved using the get_client functions. For more optional configuration, please click here.
ContainerClient	A client to interact with a specific container, although that container may not yet exist. For operations relating to a specific blob within this container, a blob client can be retrieved using the get_blob_client function. For more optional configuration, please click here.
ContainerEncryptionScope	The default encryption scope configuration for a container. This scope is used implicitly for all future writes within the container, but can be overridden per blob operation. New in version 12.2.0.
ContainerProperties	Blob container's properties class. Returned ContainerProperties instances expose these values through a dictionary interface, for example: container_props["last_modified"]. Additionally, the container name is available as container_props["name"].
ContainerSasPermissions	ContainerSasPermissions class to be used with the generate_container_sas function and for the AccessPolicies used with set_container_access_policy.
ContentSettings	The content settings of a blob.
CopyProperties	Blob Copy Properties. These properties will be None if this blob has never been the destination in a Copy Blob operation, or if this blob has been modified after a concluded Copy Blob operation, for example, using Set Blob Properties, Upload Blob, or Commit Block List.
CorsRule	CORS is an HTTP feature that enables a web application running under one domain to access resources in another domain. Web browsers implement a security restriction known as same-origin policy that prevents a web page from calling APIs in a different domain; CORS provides a secure way to allow one domain (the origin domain) to call APIs in another domain.
CustomerProvidedEncryptionKey	All data in Azure Storage is encrypted at-rest using an account-level encryption key. In versions 2018-06-17 and newer, you can manage the key used to encrypt blob contents and application metadata per-blob by providing an AES-256 encryption key in requests to the storage service. When you use a customer-provided key, Azure Storage does not manage or persist your key. When writing data to a blob, the provided key is used to encrypt your data before writing it to disk. A SHA-256 hash of the encryption key is written alongside the blob contents, and is used to verify that all subsequent operations against the blob use the same encryption key. This hash cannot be used to retrieve the encryption key or decrypt the contents of the blob. When reading a blob, the provided key is used to decrypt your data after reading it from disk. In both cases, the provided encryption key is securely discarded as soon as the encryption or decryption process completes.
DelimitedJsonDialect	Defines the input or output JSON serialization for a blob data query.
DelimitedTextDialect	Defines the input or output delimited (CSV) serialization for a blob query request.
ExponentialRetry	Exponential retry. Constructs an Exponential retry object. The initial_backoff is used for the first retry. Subsequent retries are retried after initial_backoff + increment_power^retry_count seconds.
FilteredBlob	Blob info from a Filter Blobs API call.
ImmutabilityPolicy	Optional parameters for setting the immutability policy of a blob, blob snapshot or blob version. New in version 12.10.0: This was introduced in API version '2020-10-02'.
LeaseProperties	Blob Lease Properties.
LinearRetry	Linear retry. Constructs a Linear retry object.
LocationMode	Specifies the location the request should be sent to. This mode only applies for RA-GRS accounts which allow secondary read access. All other account types must use PRIMARY.
Metrics	A summary of request statistics grouped by API in hour or minute aggregates for blobs.
ObjectReplicationPolicy	Policy id and rule ids applied to a blob.
ObjectReplicationRule	Policy id and rule ids applied to a blob.
PageRange	Page Range for page blob.
PartialBatchErrorException	There is a partial failure in batch operations.
ResourceTypes	Specifies the resource types that are accessible with the account SAS.
RetentionPolicy	The retention policy which determines how long the associated data should persist.
Services	Specifies the services accessible with the account SAS.
StaticWebsite	The properties that enable an account to host a static website.
StorageStreamDownloader	A streaming object to download from Azure Storage.
UserDelegationKey	Represents a user delegation key, provided to the user by Azure Storage based on their Azure Active Directory access token. The fields are saved as simple strings since the user does not have to interact with this object; to generate an identify SAS, the user can simply pass it to the right API.

Enums

ArrowType
BlobImmutabilityPolicyMode	Specifies the immutability policy mode to set on the blob. "Mutable" can only be returned by service, don't set to "Mutable".
BlobType
BlockState	Block blob block types.
PremiumPageBlobTier	Specifies the page blob tier to set the blob to. This is only applicable to page blobs on premium storage accounts. Please take a look at: https://docs.microsoft.com/en-us/azure/storage/storage-premium-storage#scalability-and-performance-targets for detailed information on the corresponding IOPS and throughput per PageBlobTier.
PublicAccess	Specifies whether data in the container may be accessed publicly and the level of access.
QuickQueryDialect	Specifies the quick query input/output dialect.
RehydratePriority	If an object is in rehydrate pending state then this header is returned with priority of rehydrate. Valid values are High and Standard.
SequenceNumberAction	Sequence number actions.
StandardBlobTier	Specifies the blob tier to set the blob to. This is only applicable for block blobs on standard storage accounts.
StorageErrorCode

Functions

download_blob_from_url

Download the contents of a blob to a local file or stream.

download_blob_from_url(blob_url: str, output: str | IO[bytes], credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> None

Parameters

Name	Description
blob_url Required	str The full URI to the blob. This can also include a SAS token.
output Required	str or <xref:<xref:writable stream.>> Where the data should be downloaded to. This could be either a file path to write to, or an open IO handle to write to.
credential	AzureNamedKeyCredential or AzureSasCredential or TokenCredential or str or dict[str, str] or None The credentials with which to authenticate. This is optional if the blob URL already has a SAS token or the blob is public. The value can be a SAS token string, an instance of a AzureSasCredential or AzureNamedKeyCredential from azure.core.credentials, an account shared access key, or an instance of a TokenCredentials class from azure.identity. If the resource URI already contains a SAS token, this will be ignored in favor of an explicit credential except in the case of AzureSasCredential, where the conflicting SAS tokens will raise a ValueError. If using an instance of AzureNamedKeyCredential, "name" should be the storage account name, and "key" should be the storage account key. Default value: None

Keyword-Only Parameters

Name	Description
overwrite	bool Whether the local file should be overwritten if it already exists. The default value is False - in which case a ValueError will be raised if the file already exists. If set to True, an attempt will be made to write to the existing file. If a stream handle is passed in, this value is ignored.
max_concurrency	int The number of parallel connections with which to download.
offset	int Start of byte range to use for downloading a section of the blob. Must be set if length is provided.
length	int Number of bytes to read from the stream. This is optional, but should be supplied for optimal performance.
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.

Returns

Type	Description
None

generate_account_sas

Generates a shared access signature for the blob service.

Use the returned signature with the credential parameter of any BlobServiceClient, ContainerClient or BlobClient.

generate_account_sas(account_name: str, account_key: str, resource_types: ResourceTypes | str, permission: AccountSasPermissions | str, expiry: datetime | str, start: datetime | str | None = None, ip: str | None = None, *, services: ~azure.storage.blob._shared.models.Services | str = <azure.storage.blob._shared.models.Services object>, sts_hook: ~typing.Callable[[str], None] | None = None, **kwargs: ~typing.Any) -> str

Parameters

Name	Description
account_name Required	str The storage account name used to generate the shared access signature.
account_key Required	str The account key, also called shared key or access key, to generate the shared access signature.
resource_types Required	str or ResourceTypes Specifies the resource types that are accessible with the account SAS.
permission Required	str or AccountSasPermissions The permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions.
expiry Required	datetime or str The time at which the shared access signature becomes invalid. The provided datetime will always be interpreted as UTC.
start	datetime or str The time at which the shared access signature becomes valid. If omitted, start time for this call is assumed to be the time when the storage service receives the request. The provided datetime will always be interpreted as UTC. Default value: None
ip	str Specifies an IP address or a range of IP addresses from which to accept requests. If the IP address from which the request originates does not match the IP address or address range specified on the SAS token, the request is not authenticated. For example, specifying ip=168.1.5.65 or ip=168.1.5.60-168.1.5.70 on the SAS restricts the request to those IP addresses. Default value: None

Keyword-Only Parameters

Name	Description
services	Union[Services, str] Specifies the services that the Shared Access Signature (sas) token will be able to be utilized with. Will default to only this package (i.e. blobs) if not provided. Default value: b
protocol	str Specifies the protocol permitted for a request made. The default value is https.
encryption_scope	str Specifies the encryption scope for a request made so that all write operations will be service encrypted.
sts_hook	Optional[Callable[[str], None]] For debugging purposes only. If provided, the hook is called with the string to sign that was used to generate the SAS.

Returns

Type	Description
str	A Shared Access Signature (sas) token.

generate_blob_sas

Generates a shared access signature for a blob.

Use the returned signature with the credential parameter of any BlobServiceClient, ContainerClient or BlobClient.

generate_blob_sas(account_name: str, container_name: str, blob_name: str, snapshot: str | None = None, account_key: str | None = None, user_delegation_key: UserDelegationKey | None = None, permission: BlobSasPermissions | str | None = None, expiry: datetime | str | None = None, start: datetime | str | None = None, policy_id: str | None = None, ip: str | None = None, *, sts_hook: Callable[[str], None] | None = None, **kwargs: Any) -> str

Parameters

Name	Description
account_name Required	str The storage account name used to generate the shared access signature.
container_name Required	str The name of the container.
blob_name Required	str The name of the blob.
snapshot	str An optional blob snapshot ID. Default value: None
account_key	str The account key, also called shared key or access key, to generate the shared access signature. Either account_key or user_delegation_key must be specified. Default value: None
user_delegation_key	UserDelegationKey Instead of an account shared key, the user could pass in a user delegation key. A user delegation key can be obtained from the service by authenticating with an AAD identity; this can be accomplished by calling get_user_delegation_key. When present, the SAS is signed with the user delegation key instead. Default value: None
permission	str or BlobSasPermissions The permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions. Permissions must be ordered racwdxytmei. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Default value: None
expiry	datetime or str The time at which the shared access signature becomes invalid. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Default value: None
start	datetime or str The time at which the shared access signature becomes valid. If omitted, start time for this call is assumed to be the time when the storage service receives the request. The provided datetime will always be interpreted as UTC. Default value: None
policy_id	str A unique value up to 64 characters in length that correlates to a stored access policy. To create a stored access policy, use set_container_access_policy. Default value: None
ip	str Specifies an IP address or a range of IP addresses from which to accept requests. If the IP address from which the request originates does not match the IP address or address range specified on the SAS token, the request is not authenticated. For example, specifying ip=168.1.5.65 or ip=168.1.5.60-168.1.5.70 on the SAS restricts the request to those IP addresses. Default value: None

Keyword-Only Parameters

Name	Description
version_id	str An optional blob version ID. This parameter is only applicable for versioning-enabled Storage accounts. Note that the 'versionid' query parameter is not included in the output SAS. Therefore, please provide the 'version_id' parameter to any APIs when using the output SAS to operate on a specific version. New in version 12.4.0: This keyword argument was introduced in API version '2019-12-12'.
protocol	str Specifies the protocol permitted for a request made. The default value is https.
cache_control	str Response header value for Cache-Control when resource is accessed using this shared access signature.
content_disposition	str Response header value for Content-Disposition when resource is accessed using this shared access signature.
content_encoding	str Response header value for Content-Encoding when resource is accessed using this shared access signature.
content_language	str Response header value for Content-Language when resource is accessed using this shared access signature.
content_type	str Response header value for Content-Type when resource is accessed using this shared access signature.
encryption_scope	str Specifies the encryption scope for a request made so that all write operations will be service encrypted.
correlation_id	str The correlation id to correlate the storage audit logs with the audit logs used by the principal generating and distributing the SAS. This can only be used when generating a SAS with delegation key.
sts_hook	Optional[Callable[[str], None]] For debugging purposes only. If provided, the hook is called with the string to sign that was used to generate the SAS.

Returns

Type	Description
str	A Shared Access Signature (sas) token.

generate_container_sas

Generates a shared access signature for a container.

Use the returned signature with the credential parameter of any BlobServiceClient, ContainerClient or BlobClient.

generate_container_sas(account_name: str, container_name: str, account_key: str | None = None, user_delegation_key: UserDelegationKey | None = None, permission: ContainerSasPermissions | str | None = None, expiry: datetime | str | None = None, start: datetime | str | None = None, policy_id: str | None = None, ip: str | None = None, *, sts_hook: Callable[[str], None] | None = None, **kwargs: Any) -> str

Parameters

Name	Description
account_name Required	str The storage account name used to generate the shared access signature.
container_name Required	str The name of the container.
account_key	str The account key, also called shared key or access key, to generate the shared access signature. Either account_key or user_delegation_key must be specified. Default value: None
user_delegation_key	UserDelegationKey Instead of an account shared key, the user could pass in a user delegation key. A user delegation key can be obtained from the service by authenticating with an AAD identity; this can be accomplished by calling get_user_delegation_key. When present, the SAS is signed with the user delegation key instead. Default value: None
permission	str or ContainerSasPermissions The permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions. Permissions must be ordered racwdxyltfmei. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Default value: None
expiry	datetime or str The time at which the shared access signature becomes invalid. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Default value: None
start	datetime or str The time at which the shared access signature becomes valid. If omitted, start time for this call is assumed to be the time when the storage service receives the request. The provided datetime will always be interpreted as UTC. Default value: None
policy_id	str A unique value up to 64 characters in length that correlates to a stored access policy. To create a stored access policy, use set_container_access_policy. Default value: None
ip	str Specifies an IP address or a range of IP addresses from which to accept requests. If the IP address from which the request originates does not match the IP address or address range specified on the SAS token, the request is not authenticated. For example, specifying ip=168.1.5.65 or ip=168.1.5.60-168.1.5.70 on the SAS restricts the request to those IP addresses. Default value: None

Keyword-Only Parameters

Name	Description
protocol	str Specifies the protocol permitted for a request made. The default value is https.
cache_control	str Response header value for Cache-Control when resource is accessed using this shared access signature.
content_disposition	str Response header value for Content-Disposition when resource is accessed using this shared access signature.
content_encoding	str Response header value for Content-Encoding when resource is accessed using this shared access signature.
content_language	str Response header value for Content-Language when resource is accessed using this shared access signature.
content_type	str Response header value for Content-Type when resource is accessed using this shared access signature.
encryption_scope	str Specifies the encryption scope for a request made so that all write operations will be service encrypted.
correlation_id	str The correlation id to correlate the storage audit logs with the audit logs used by the principal generating and distributing the SAS. This can only be used when generating a SAS with delegation key.
sts_hook	Optional[Callable[[str], None]] For debugging purposes only. If provided, the hook is called with the string to sign that was used to generate the SAS.

Returns

Type	Description
str	A Shared Access Signature (sas) token.

upload_blob_to_url

Upload data to a given URL

The data will be uploaded as a block blob.

upload_blob_to_url(blob_url: str, data: Iterable | IO, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Dict[str, Any]

Parameters

Name	Description
blob_url Required	str The full URI to the blob. This can also include a SAS token.
data Required	bytes or str or Iterable The data to upload. This can be bytes, text, an iterable or a file-like object.
credential	AzureNamedKeyCredential or AzureSasCredential or TokenCredential or str or dict[str, str] or None The credentials with which to authenticate. This is optional if the blob URL already has a SAS token. The value can be a SAS token string, an instance of a AzureSasCredential or AzureNamedKeyCredential from azure.core.credentials, an account shared access key, or an instance of a TokenCredentials class from azure.identity. If the resource URI already contains a SAS token, this will be ignored in favor of an explicit credential except in the case of AzureSasCredential, where the conflicting SAS tokens will raise a ValueError. If using an instance of AzureNamedKeyCredential, "name" should be the storage account name, and "key" should be the storage account key. Default value: None

Keyword-Only Parameters

Name	Description
overwrite	bool Whether the blob to be uploaded should overwrite the current data. If True, upload_blob_to_url will overwrite any existing data. If set to False, the operation will fail with a ResourceExistsError.
max_concurrency	int The number of parallel connections with which to download.
length	int Number of bytes to read from the stream. This is optional, but should be supplied for optimal performance.
metadata	dict(str,str) Name-value pairs associated with the blob as metadata.
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.
encoding	str Encoding to use if text is supplied as input. Defaults to UTF-8.

Returns

Type	Description
dict(str, Any)	Blob-updated property dict (Etag and last modified)