Blobs / Objects

Create / interact with Google Cloud Storage blobs.

class google.cloud.storage.blob.Blob(name, bucket, chunk_size=None, encryption_key=None, kms_key_name=None, generation=None)

Bases:google.cloud.storage._helpers._PropertyMixin

A wrapper around Cloud Storage’s concept of anObject.

  • Parameters

    • name (str) – The name of the blob. This corresponds to the unique path ofthe object in the bucket. If bytes, will be converted to aunicode object. Blob / object names can contain any sequenceof valid unicode characters, of length 1-1024 bytes whenUTF-8 encoded.

    • bucket (google.cloud.storage.bucket.Bucket) – The bucket to which this blob belongs.

    • chunk_size (int) – (Optional) The size of a chunk of data whenever iterating (in bytes).This must be a multiple of 256 KB per the API specification. If notspecified, the chunk_size of the blob itself is used. If that is notspecified, a default value of 40 MB is used.

    • encryption_key (bytes) – (Optional) 32 byte encryption key for customer-supplied encryption.Seehttps://cloud.google.com/storage/docs/encryption#customer-supplied.

    • kms_key_name (str) – (Optional) Resource name of Cloud KMS key used to encrypt the blob’scontents.

    • generation (long) – (Optional) If present, selects a specific revision of this object.

propertyname

Get the blob’s name.

STORAGE_CLASSES( = ('STANDARD', 'NEARLINE', 'COLDLINE', 'ARCHIVE', 'MULTI_REGIONAL', 'REGIONAL' )

Allowed values forstorage_class.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects#storageClasshttps://cloud.google.com/storage/docs/per-object-storage-class

NOTE: This list does not include ‘DURABLE_REDUCED_AVAILABILITY’, whichis only documented for buckets (and deprecated).

property acl()

Create our ACL on demand.

property bucket()

Bucket which contains the object.

  • Return type

    Bucket

  • Returns

    The object’s bucket.

property cache_control()

HTTP ‘Cache-Control’ header for this object.

SeeRFC 7234andAPI reference docs.

  • Return type

    str orNoneType

property chunk_size()

Get the blob’s default chunk size.

  • Return type

    int orNoneType

  • Returns

    The current blob’s chunk size, if it is set.

property client()

The client bound to this blob.

property component_count()

Number of underlying components that make up this object.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects

  • Return type

    int orNoneType

  • Returns

    The component count (in case of a composed object) orNone if the blob’s resource has not been loaded from the server. This property will not be set on objects not created viacompose.

compose(sources, client=None, timeout=60, if_generation_match=None, if_metageneration_match=None, if_source_generation_match=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object>)

Concatenate source blobs into this one.

Ifuser_project is set on the bucket, bills the API requestto that project.

  • Parameters

    • sources (list ofBlob) – Blobs whose contents will be composed into this blob.

    • client (Client) – (Optional) The client to use. If not passed, falls back to theclient stored on the blob’s bucket.

    • timeout (float* or[tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to waitfor the server response. See:Configuring Timeouts

    • if_generation_match (long) – (Optional) Makes the operation conditional on whether thedestination object’s current generation matches the given value.Setting to 0 makes the operation succeed only if there are no liveversions of the object.

      NOTE: In a previous version, this argument worked identically to theif_source_generation_match argument. Forbackwards-compatibility reasons, if a list is passed in,this argument will behave likeif_source_generation_matchand also issue a DeprecationWarning.

    • if_metageneration_match (long) – (Optional) Makes the operation conditional on whether thedestination object’s current metageneration matches the givenvalue.

      If a list of long is passed in, no match operation will beperformed. (Deprecated: type(list of long) is supported forbackwards-compatability reasons only.)

    • if_source_generation_match (list of long) – (Optional) Makes the operation conditional on whether the currentgeneration of each source blob matches the corresponding generation.The list must matchsources item-to-item.

    • retry (google.api_core.retry.Retry* or[google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. See:Configuring Retries

Example

Compose blobs using source generation match preconditions.

>>> from google.cloud importstorage>>> client =storage.Client()>>> bucket = client.bucket("bucket-name")
>>> blobs = [bucket.blob("blob-name-1"), bucket.blob("blob-name-2")]>>> if_source_generation_match = [None] * len(blobs)>>> if_source_generation_match[0] = "123"  # precondition for "blob-name-1"
>>> composed_blob = bucket.blob("composed-name")>>> composed_blob.compose(blobs, if_source_generation_match=if_source_generation_match)

property content_disposition()

HTTP ‘Content-Disposition’ header for this object.

SeeRFC 6266 andAPI reference docs.

  • Return type

    str orNoneType

property content_encoding()

HTTP ‘Content-Encoding’ header for this object.

SeeRFC 7231 andAPI reference docs.

  • Return type

    str orNoneType

property content_language()

HTTP ‘Content-Language’ header for this object.

SeeBCP47 andAPI reference docs.

  • Return type

    str orNoneType

property content_type()

HTTP ‘Content-Type’ header for this object.

SeeRFC 2616 andAPI reference docs.

  • Return type

    str orNoneType

property crc32c()

CRC32C checksum for this object.

This returns the blob’s CRC32C checksum. To retrieve the value, first use areload method of the Blob class which loads the blob’s properties from the server.

SeeRFC 4960 andAPI reference docs.

If not set before upload, the server will compute the hash.

  • Return type

    str orNoneType

Example

Retrieve the crc32c hash of blob.

>>> from google.cloud importstorage>>> client =storage.Client()>>> bucket = client.get_bucket("my-bucket-name")>>> blob = bucket.blob('my-blob')
>>> blob.crc32c  # return None>>> blob.reload()>>> blob.crc32c  # return crc32c hash
>>> # Another approach>>> blob = bucket.get_blob('my-blob')>>> blob.crc32c  # return crc32c hash

create_resumable_upload_session(content_type=None, size=None, origin=None, client=None, timeout=60, checksum=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object>)

Create a resumable upload session.

Resumable upload sessions allow you to start an upload session fromone client and complete the session in another. This method is calledby the initiator to set the metadata and limits. The initiator thenpasses the session URL to the client that will upload the binary data.The client performs a PUT request on the session URL to complete theupload. This process allows untrusted clients to upload to anaccess-controlled bucket. For more details, see thedocumentation on signed URLs.

The content type of the upload will be determined in orderof precedence:

  • The value passed in to this method (if notNone)

  • The value stored on the current blob

  • The default value (‘application/octet-stream’)

NOTE: The effect of uploading to an existing blob depends on the“versioning” and “lifecycle” policies defined on the blob’sbucket. In the absence of those policies, upload willoverwrite any existing contents.

See theobject versioning andlifecycleAPI documents for details.

Ifencryption_key is set, the blob will be encrypted withacustomer-suppliedencryption key.

Ifuser_project is set on the bucket, bills the API requestto that project.

  • Parameters

    • size (int) – (Optional) The maximum number of bytes that can be uploaded usingthis session. If the size is not known when creating the session,this should be left blank.

    • content_type (str) – (Optional) Type of content being uploaded.

    • origin (str) – (Optional) If set, the upload can only be completed by a user-agentthat uploads from the given origin. This can be useful when passingthe session to a web client.

    • client (Client) – (Optional) The client to use. If not passed, falls back to theclient stored on the blob’s bucket.

    • timeout (float* or[tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to waitfor the server response. See:Configuring Timeouts

    • checksum (str) – (Optional) The type of checksum to compute to verifythe integrity of the object. After the upload is complete, theserver-computed checksum of the resulting object will be checkedand google.resumable_media.common.DataCorruption will be raised ona mismatch. On a validation failure, the client will attempt todelete the uploaded object automatically. Supported valuesare “md5”, “crc32c” and None. The default is None.

    • if_generation_match (long) – (Optional) SeeUsing if_generation_match

    • if_generation_not_match (long) – (Optional) SeeUsing if_generation_not_match

    • if_metageneration_match (long) – (Optional) SeeUsing if_metageneration_match

    • if_metageneration_not_match (long) – (Optional) SeeUsing if_metageneration_not_match

    • retry (google.api_core.retry.Retry* or[google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disableretries. A google.api_core.retry.Retry value will enable retries,and the object will define retriable response codes and errors andconfigure backoff and timeout options.A google.cloud.storage.retry.ConditionalRetryPolicy value wraps aRetry object and activates it only if certain conditions are met.This class exists to provide safe defaults for RPC calls that arenot technically safe to retry normally (due to potential dataduplication or other side-effects) but become safe to retry if acondition such as if_generation_match is set.See the retry.py source code and docstrings in this package(google.cloud.storage.retry) for information on retry types and howto configure them.Media operations (downloads and uploads) do not support non-defaultpredicates in a Retry object. The default will always be used. Otherconfiguration changes for Retry objects such as delays and deadlinesare respected.

  • Return type

    str

  • Returns

    The resumable upload session URL. The upload can be completed by making an HTTP PUT request with the file’s contents.

  • Raises

    google.cloud.exceptions.GoogleCloudError if the session creation response returns an error status.

property custom_time()

Retrieve the custom time for the object.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects

  • Return type

    datetime.datetime orNoneType

  • Returns

    Datetime object parsed from RFC3339 valid timestamp, orNone if the blob’s resource has not been loaded from the server (seereload()).

delete(client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object>)

Deletes a blob from Cloud Storage.

Ifuser_project is set on the bucket, bills the API requestto that project.

download_as_bytes(client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='md5', retry=<google.api_core.retry.Retry object>)

Download the contents of this blob as a bytes object.

Ifuser_project is set on the bucket, bills the API requestto that project.

  • Parameters

    • client (Client) – (Optional) The client to use. If not passed, falls back to theclient stored on the blob’s bucket.

    • start (int) – (Optional) The first byte in a range to be downloaded.

    • end (int) – (Optional) The last byte in a range to be downloaded.

    • raw_download (bool) – (Optional) If true, download the object without any expansion.

    • if_etag_match (Union[str, **Set[str]]) – (Optional) SeeUsing if_etag_match

    • if_etag_not_match (Union[str, **Set[str]]) – (Optional) SeeUsing if_etag_not_match

    • if_generation_match (long) – (Optional) SeeUsing if_generation_match

    • if_generation_not_match (long) – (Optional) SeeUsing if_generation_not_match

    • if_metageneration_match (long) – (Optional) SeeUsing if_metageneration_match

    • if_metageneration_not_match (long) – (Optional) SeeUsing if_metageneration_not_match

    • timeout (float* or[tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to waitfor the server response. See:Configuring Timeouts

    • checksum (str) – (Optional) The type of checksum to compute to verify the integrityof the object. The response headers must contain a checksum of therequested type. If the headers lack an appropriate checksum (forinstance in the case of transcoded or ranged downloads where theremote service does not know the correct checksum, includingdownloads where chunk_size is set) an INFO-level log will beemitted. Supported values are “md5”, “crc32c” and None. The defaultis “md5”.

    • retry (google.api_core.retry.Retry* or[google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disableretries. A google.api_core.retry.Retry value will enable retries,and the object will define retriable response codes and errors andconfigure backoff and timeout options.

      A google.cloud.storage.retry.ConditionalRetryPolicy value wraps aRetry object and activates it only if certain conditions are met.This class exists to provide safe defaults for RPC calls that arenot technically safe to retry normally (due to potential dataduplication or other side-effects) but become safe to retry if acondition such as if_metageneration_match is set.

      See the retry.py source code and docstrings in this package(google.cloud.storage.retry) for information on retry types and howto configure them.

      Media operations (downloads and uploads) do not support non-defaultpredicates in a Retry object. The default will always be used. Otherconfiguration changes for Retry objects such as delays and deadlinesare respected.

  • Return type

    bytes

  • Returns

    The data stored in this blob.

  • Raises

    google.cloud.exceptions.NotFound

download_as_string(client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.Retry object>)

(Deprecated) Download the contents of this blob as a bytes object.

Ifuser_project is set on the bucket, bills the API requestto that project.

NOTE: Deprecated alias fordownload_as_bytes().

  • Parameters

    • client (Client) – (Optional) The client to use. If not passed, falls back to theclient stored on the blob’s bucket.

    • start (int) – (Optional) The first byte in a range to be downloaded.

    • end (int) – (Optional) The last byte in a range to be downloaded.

    • raw_download (bool) – (Optional) If true, download the object without any expansion.

    • if_etag_match (Union[str, **Set[str]]) – (Optional) SeeUsing if_etag_match

    • if_etag_not_match (Union[str, **Set[str]]) – (Optional) SeeUsing if_etag_not_match

    • if_generation_match (long) – (Optional) SeeUsing if_generation_match

    • if_generation_not_match (long) – (Optional) SeeUsing if_generation_not_match

    • if_metageneration_match (long) – (Optional) SeeUsing if_metageneration_match

    • if_metageneration_not_match (long) – (Optional) SeeUsing if_metageneration_not_match

    • timeout (float* or[tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to waitfor the server response. See:Configuring Timeouts

    • retry (google.api_core.retry.Retry* or[google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disableretries. A google.api_core.retry.Retry value will enable retries,and the object will define retriable response codes and errors andconfigure backoff and timeout options.

      A google.cloud.storage.retry.ConditionalRetryPolicy value wraps aRetry object and activates it only if certain conditions are met.This class exists to provide safe defaults for RPC calls that arenot technically safe to retry normally (due to potential dataduplication or other side-effects) but become safe to retry if acondition such as if_metageneration_match is set.

      See the retry.py source code and docstrings in this package(google.cloud.storage.retry) for information on retry types and howto configure them.

      Media operations (downloads and uploads) do not support non-defaultpredicates in a Retry object. The default will always be used. Otherconfiguration changes for Retry objects such as delays and deadlinesare respected.

  • Return type

    bytes

  • Returns

    The data stored in this blob.

  • Raises

    google.cloud.exceptions.NotFound

download_as_text(client=None, start=None, end=None, raw_download=False, encoding=None, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.Retry object>)

Download the contents of this blob as text (not bytes).

Ifuser_project is set on the bucket, bills the API requestto that project.

  • Parameters

    • client (Client) – (Optional) The client to use. If not passed, falls back to theclient stored on the blob’s bucket.

    • start (int) – (Optional) The first byte in a range to be downloaded.

    • end (int) – (Optional) The last byte in a range to be downloaded.

    • raw_download (bool) – (Optional) If true, download the object without any expansion.

    • encoding (str) – (Optional) encoding to be used to decode thedownloaded bytes. Defaults to thecharset param ofattr:content_type, or else to “utf-8”.

    • if_etag_match (Union[str, **Set[str]]) – (Optional) SeeUsing if_etag_match

    • if_etag_not_match (Union[str, **Set[str]]) – (Optional) SeeUsing if_etag_not_match

    • if_generation_match (long) – (Optional) SeeUsing if_generation_match

    • if_generation_not_match (long) – (Optional) SeeUsing if_generation_not_match

    • if_metageneration_match (long) – (Optional) SeeUsing if_metageneration_match

    • if_metageneration_not_match (long) – (Optional) SeeUsing if_metageneration_not_match

    • timeout (float* or[tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to waitfor the server response. See:Configuring Timeouts

    • retry (google.api_core.retry.Retry* or[google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disableretries. A google.api_core.retry.Retry value will enable retries,and the object will define retriable response codes and errors andconfigure backoff and timeout options.

      A google.cloud.storage.retry.ConditionalRetryPolicy value wraps aRetry object and activates it only if certain conditions are met.This class exists to provide safe defaults for RPC calls that arenot technically safe to retry normally (due to potential dataduplication or other side-effects) but become safe to retry if acondition such as if_metageneration_match is set.

      See the retry.py source code and docstrings in this package(google.cloud.storage.retry) for information on retry types and howto configure them.

      Media operations (downloads and uploads) do not support non-defaultpredicates in a Retry object. The default will always be used. Otherconfiguration changes for Retry objects such as delays and deadlinesare respected.

  • Return type

    text

  • Returns

    The data stored in this blob, decoded to text.

download_to_file(file_obj, client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='md5', retry=<google.api_core.retry.Retry object>)

DEPRECATED. Download the contents of this blob into a file-like object.

NOTE: If the server-set property,media_link, is not yetinitialized, makes an additional API request to load it.

Downloading a file that has been encrypted with acustomer-suppliedencryption key:

from google.cloud.storage importBlobclient =storage.Client(project="my-project")bucket = client.get_bucket("my-bucket")encryption_key = "c7f32af42e45e85b9848a6a14dd2a8f6"blob = Blob("secure-data", bucket, encryption_key=encryption_key)blob.upload_from_string("my secret message.")with open("/tmp/my-secure-file", "wb") as file_obj:    client.download_to_file(blob, file_obj)

Theencryption_key should be a str or bytes with a length of atleast 32.

If thechunk_size of a current blob is None, will download datain single download request otherwise it will download thechunk_sizeof data in each request.

For more fine-grained control over the download process, check outgoogle-resumable-media.For example, this library allows downloadingparts of a blob rather than the whole thing.

Ifuser_project is set on the bucket, bills the API requestto that project.

  • Parameters

    • file_obj (file) – A file handle to which to write the blob’s data.

    • client (Client) – (Optional) The client to use. If not passed, falls back to theclient stored on the blob’s bucket.

    • start (int) – (Optional) The first byte in a range to be downloaded.

    • end (int) – (Optional) The last byte in a range to be downloaded.

    • raw_download (bool) – (Optional) If true, download the object without any expansion.

    • if_etag_match (Union[str, **Set[str]]) – (Optional) SeeUsing if_etag_match

    • if_etag_not_match (Union[str, **Set[str]]) – (Optional) SeeUsing if_etag_not_match

    • if_generation_match (long) – (Optional) SeeUsing if_generation_match

    • if_generation_not_match (long) – (Optional) SeeUsing if_generation_not_match

    • if_metageneration_match (long) – (Optional) SeeUsing if_metageneration_match

    • if_metageneration_not_match (long) – (Optional) SeeUsing if_metageneration_not_match

    • timeout (float* or[tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to waitfor the server response. See:Configuring Timeouts

    • checksum (str) – (Optional) The type of checksum to compute to verify the integrityof the object. The response headers must contain a checksum of therequested type. If the headers lack an appropriate checksum (forinstance in the case of transcoded or ranged downloads where theremote service does not know the correct checksum, includingdownloads where chunk_size is set) an INFO-level log will beemitted. Supported values are “md5”, “crc32c” and None. The defaultis “md5”.

    • retry (google.api_core.retry.Retry* or[google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disableretries. A google.api_core.retry.Retry value will enable retries,and the object will define retriable response codes and errors andconfigure backoff and timeout options.

      A google.cloud.storage.retry.ConditionalRetryPolicy value wraps aRetry object and activates it only if certain conditions are met.This class exists to provide safe defaults for RPC calls that arenot technically safe to retry normally (due to potential dataduplication or other side-effects) but become safe to retry if acondition such as if_metageneration_match is set.

      See the retry.py source code and docstrings in this package(google.cloud.storage.retry) for information on retry types and howto configure them.

      Media operations (downloads and uploads) do not support non-defaultpredicates in a Retry object. The default will always be used. Otherconfiguration changes for Retry objects such as delays and deadlinesare respected.

  • Raises

    google.cloud.exceptions.NotFound

download_to_filename(filename, client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='md5', retry=<google.api_core.retry.Retry object>)

Download the contents of this blob into a named file.

Ifuser_project is set on the bucket, bills the API requestto that project.

  • Parameters

    • filename (str) – A filename to be passed toopen.

    • client (Client) – (Optional) The client to use. If not passed, falls back to theclient stored on the blob’s bucket.

    • start (int) – (Optional) The first byte in a range to be downloaded.

    • end (int) – (Optional) The last byte in a range to be downloaded.

    • raw_download (bool) – (Optional) If true, download the object without any expansion.

    • if_etag_match (Union[str, **Set[str]]) – (Optional) SeeUsing if_etag_match

    • if_etag_not_match (Union[str, **Set[str]]) – (Optional) SeeUsing if_etag_not_match

    • if_generation_match (long) – (Optional) SeeUsing if_generation_match

    • if_generation_not_match (long) – (Optional) SeeUsing if_generation_not_match

    • if_metageneration_match (long) – (Optional) SeeUsing if_metageneration_match

    • if_metageneration_not_match (long) – (Optional) SeeUsing if_metageneration_not_match

    • timeout (float* or[tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to waitfor the server response. See:Configuring Timeouts

    • checksum (str) – (Optional) The type of checksum to compute to verify the integrityof the object. The response headers must contain a checksum of therequested type. If the headers lack an appropriate checksum (forinstance in the case of transcoded or ranged downloads where theremote service does not know the correct checksum, includingdownloads where chunk_size is set) an INFO-level log will beemitted. Supported values are “md5”, “crc32c” and None. The defaultis “md5”.

    • retry (google.api_core.retry.Retry* or[google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disableretries. A google.api_core.retry.Retry value will enable retries,and the object will define retriable response codes and errors andconfigure backoff and timeout options.

      A google.cloud.storage.retry.ConditionalRetryPolicy value wraps aRetry object and activates it only if certain conditions are met.This class exists to provide safe defaults for RPC calls that arenot technically safe to retry normally (due to potential dataduplication or other side-effects) but become safe to retry if acondition such as if_metageneration_match is set.

      See the retry.py source code and docstrings in this package(google.cloud.storage.retry) for information on retry types and howto configure them.

      Media operations (downloads and uploads) do not support non-defaultpredicates in a Retry object. The default will always be used. Otherconfiguration changes for Retry objects such as delays and deadlinesare respected.

  • Raises

    google.cloud.exceptions.NotFound

property encryption_key()

Retrieve the customer-supplied encryption key for the object.

  • Return type

    bytes orNoneType

  • Returns

    The encryption key orNone if no customer-supplied encryption key was used, or the blob’s resource has not been loaded from the server.

property etag()

Retrieve the ETag for the object.

SeeRFC 2616 (etags) andAPI reference docs.

  • Return type

    str orNoneType

  • Returns

    The blob etag orNone if the blob’s resource has not been loaded from the server.

property event_based_hold()

Is an event-based hold active on the object?

SeeAPI reference docs.

If the property is not set locally, returnsNone.

  • Return type

    bool orNoneType

exists(client=None, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.Retry object>)

Determines whether or not this blob exists.

Ifuser_project is set on the bucket, bills the API requestto that project.

classmethod from_string(uri, client=None)

Get a constructor for blob object by URI.

  • Parameters

    • uri (str) – The blob uri pass to get blob object.

    • client (Client) – (Optional) The client to use. Application code shouldalways passclient.

  • Return type

    google.cloud.storage.blob.Blob

  • Returns

    The blob object created.

Example

Get a constructor for blob object by URI.

>>> from google.cloud importstorage>>> from google.cloud.storage.blob importBlob>>> client =storage.Client()>>> blob =Blob.from_string("gs://bucket/object", client=client)

generate_signed_url(expiration=None, api_access_endpoint='https://storage.googleapis.com', method='GET', content_md5=None, content_type=None, response_disposition=None, response_type=None, generation=None, headers=None, query_parameters=None, client=None, credentials=None, version=None, service_account_email=None, access_token=None, virtual_hosted_style=False, bucket_bound_hostname=None, scheme='http')

Generates a signed URL for this blob.

NOTE: If you are on Google Compute Engine, you can’t generate a signedURL using GCE service account. FollowIssue 50 for updates onthis. If you’d like to be able to generate a signed URL from GCE,you can use a standard service account from a JSON file ratherthan a GCE service account.

If you have a blob that you want to allow access to for a setamount of time, you can use this method to generate a URL thatis only valid within a certain time period.

Ifbucket_bound_hostname is set as an argument ofapi_access_endpoint,https works only if using aCDN.

Example

Generates a signed URL for this blob using bucket_bound_hostname and scheme.

>>> from google.cloud importstorage>>> client =storage.Client()>>> bucket = client.get_bucket('my-bucket-name')>>> blob = bucket.get_blob('my-blob-name')>>> url = blob.generate_signed_url(expiration='url-expiration-time', bucket_bound_hostname='mydomain.tld',>>>                                  version='v4')>>> url = blob.generate_signed_url(expiration='url-expiration-time', bucket_bound_hostname='mydomain.tld',>>>                                  version='v4',scheme='https')  # If using ``CDN``

This is particularly useful if you don’t want publiclyaccessible blobs, but don’t want to require users to explicitlylog in.

  • Parameters

    • expiration (Union[Integer, *[datetime.datetime](https://python.readthedocs.io/en/latest/library/datetime.html#datetime.datetime),[datetime.timedelta](https://python.readthedocs.io/en/latest/library/datetime.html#datetime.timedelta)]*) – Point in time when the signed URL should expire. If adatetimeinstance is passed without an explicittzinfo set, it will beassumed to beUTC.

    • api_access_endpoint (str) – (Optional) URI base.

    • method (str) – The HTTP verb that will be used when requesting the URL.

    • content_md5 (str) – (Optional) The MD5 hash of the object referenced byresource.

    • content_type (str) – (Optional) The content type of the object referenced byresource.

    • response_disposition (str) – (Optional) Content disposition of responses to requests for thesigned URL. For example, to enable the signed URL to initiate afile ofblog.png, use the value'attachment;filename=blob.png'.

    • response_type (str) – (Optional) Content type of responses to requests for the signedURL. Ignored if content_type is set on object/blob metadata.

    • generation (str) – (Optional) A value that indicates which generation of the resourceto fetch.

    • headers (dict) – (Optional) Additional HTTP headers to be included as part of thesigned URLs. See:https://cloud.google.com/storage/docs/xml-api/reference-headersRequests using the signed URLmust pass the specified header(name and value) with each request for the URL.

    • query_parameters (dict) – (Optional) Additional query parameters to be included as part of thesigned URLs. See:https://cloud.google.com/storage/docs/xml-api/reference-headers#query

    • client (Client) – (Optional) The client to use. If not passed, falls back to theclient stored on the blob’s bucket.

    • credentials (google.auth.credentials.Credentials) – (Optional) The authorization credentials to attach to requests.These credentials identify this application to the service. Ifnone are specified, the client will attempt to ascertain thecredentials from the environment.

    • version (str) – (Optional) The version of signed credential to create. Must be oneof ‘v2’ | ‘v4’.

    • service_account_email (str) – (Optional) E-mail address of the service account.

    • access_token (str) – (Optional) Access token for a service account.

    • virtual_hosted_style (bool) – (Optional) If true, then construct the URL relative the bucket’svirtual hostname, e.g., ‘

    • bucket_bound_hostname (str) – (Optional) If passed, then construct the URL relative to thebucket-bound hostname. Value can be a bare or with scheme, e.g.,‘example.com’ or ‘http://example.com’. See:https://cloud.google.com/storage/docs/request-endpoints#cname

    • scheme (str) – (Optional) Ifbucket_bound_hostname is passed as a barehostname, use this value as the scheme.https will work onlywhen using a CDN. Defaults to"http".

  • Raises

    ValueError when version is invalid.

  • Raises

    TypeError when expiration is not a valid type.

  • Raises

    AttributeError if credentials is not an instance ofgoogle.auth.credentials.Signing.

  • Return type

    str

  • Returns

    A signed URL you can use to access the resource until expiration.

property generation()

Retrieve the generation for the object.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects

  • Return type

    int orNoneType

  • Returns

    The generation of the blob orNone if the blob’s resource has not been loaded from the server.

get_iam_policy(client=None, requested_policy_version=None, timeout=60, retry=<google.api_core.retry.Retry object>)

Retrieve the IAM policy for the object.

NOTE: Blob- / object-level IAM support does not yet exist and methodscurrently call an internal ACL backend not providing any utilitybeyond the blob’sacl at this time. The API may be enhancedin the future and is currently undocumented. Useacl formanaging object access control.

Ifuser_project is set on the bucket, bills the API requestto that project.

  • Parameters

    • client (Client) – (Optional) The client to use. If not passed, falls back to theclient stored on the current object’s bucket.

    • requested_policy_version (int orNoneType) – (Optional) The version of IAM policies to request. If a policywith a condition is requested without setting this, the server willreturn an error. This must be set to a value of 3 to retrieve IAMpolicies containing conditions. This is to prevent client code thatisn’t aware of IAM conditions from interpreting and modifyingpolicies incorrectly. The service might return a policy withversion lower than the one that was requested, based on the featuresyntax in the policy fetched.

    • timeout (float* or[tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to waitfor the server response. See:Configuring Timeouts

    • retry (google.api_core.retry.Retry* or[google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. See:Configuring Retries

  • Return type

    google.api_core.iam.Policy

  • Returns

    the policy instance, based on the resource returned from thegetIamPolicy API request.

property id()

Retrieve the ID for the object.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects

The ID consists of the bucket name, object name, and generation number.

  • Return type

    str orNoneType

  • Returns

    The ID of the blob orNone if the blob’s resource has not been loaded from the server.

property kms_key_name()

Resource name of Cloud KMS key used to encrypt the blob’s contents.

  • Return type

    str orNoneType

  • Returns

    The resource name orNone if no Cloud KMS key was used, or the blob’s resource has not been loaded from the server.

make_private(client=None, timeout=60, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object>)

Update blob’s ACL, revoking read access for anonymous users.

make_public(client=None, timeout=60, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object>)

Update blob’s ACL, granting read access to anonymous users.

property md5_hash()

MD5 hash for this object.

This returns the blob’s MD5 hash. To retrieve the value, first use areload method of the Blob class which loads the blob’s properties from the server.

SeeRFC 1321 andAPI reference docs.

If not set before upload, the server will compute the hash.

  • Return type

    str orNoneType

Example

Retrieve the md5 hash of blob.

>>> from google.cloud importstorage>>> client =storage.Client()>>> bucket = client.get_bucket("my-bucket-name")>>> blob = bucket.blob('my-blob')
>>> blob.md5_hash  # return None>>> blob.reload()>>> blob.md5_hash  # return md5 hash
>>> # Another approach>>> blob = bucket.get_blob('my-blob')>>> blob.md5_hash  # return md5 hash

property media_link()

Retrieve the media download URI for the object.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects

  • Return type

    str orNoneType

  • Returns

    The media link for the blob orNone if the blob’s resource has not been loaded from the server.

property metadata()

Retrieve arbitrary/application specific metadata for the object.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects

  • Setter

    Update arbitrary/application specific metadata for the object.

  • Getter

    Retrieve arbitrary/application specific metadata for the object.

  • Return type

    dict orNoneType

  • Returns

    The metadata associated with the blob orNone if the property is not set.

property metageneration()

Retrieve the metageneration for the object.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects

  • Return type

    int orNoneType

  • Returns

    The metageneration of the blob orNone if the blob’s resource has not been loaded from the server.

open(mode='r', chunk_size=None, ignore_flush=None, encoding=None, errors=None, newline=None, **kwargs)

Create a file handler for file-like I/O to or from this blob.

This method can be used as a context manager, just like Python’sbuilt-in ‘open()’ function.

While reading, as with other read methods, if blob.generation is not setthe most recent blob generation will be used. Because the file-like IOreader downloads progressively in chunks, this could result in data frommultiple versions being mixed together. If this is a concern, useeither bucket.get_blob(), or blob.reload(), which will download thelatest generation number and set it; or, if the generation is known, setit manually, for instance with bucket.blob(generation=123456).

Checksumming (hashing) to verify data integrity is disabled for readsusing this feature because reads are implemented using request ranges,which do not provide checksums to validate. Seehttps://cloud.google.com/storage/docs/hashes-etags for details.

  • Parameters

    • mode (str) – (Optional) A mode string, as per standard Python open() semantics.The firstcharacter must be ‘r’, to open the blob for reading, or ‘w’ to openit for writing. The second character, if present, must be ‘t’ for(unicode) text mode, or ‘b’ for bytes mode. If the second characteris omitted, text mode is the default.

    • chunk_size (long) – (Optional) For reads, the minimum number of bytes to read at a time.If fewer bytes than the chunk_size are requested, the remainder isbuffered. For writes, the maximum number of bytes to buffer beforesending data to the server, and the size of each request when datais sent. Writes are implemented as a “resumable upload”, sochunk_size for writes must be exactly a multiple of 256KiB as withother resumable uploads. The default is 40 MiB.

    • ignore_flush (bool) – (Optional) For non text-mode writes, makes flush() do nothinginstead of raising an error. flush() without closing is notsupported by the remote service and therefore calling it normallyresults in io.UnsupportedOperation. However, that behavior isincompatible with some consumers and wrappers of file objects inPython, such as zipfile.ZipFile or io.TextIOWrapper. Settingignore_flush will cause flush() to successfully do nothing, forcompatibility with those contexts. The correct way to actually flushdata to the remote server is to close() (using a context manager,such as in the example, will cause this to happen automatically).

    • encoding (str) – (Optional) For text mode only, the name of the encoding that the stream willbe decoded or encoded with. If omitted, it defaults tolocale.getpreferredencoding(False).

    • errors (str) – (Optional) For text mode only, an optional string that specifies how encodingand decoding errors are to be handled. Pass ‘strict’ to raise aValueError exception if there is an encoding error (the default ofNone has the same effect), or pass ‘ignore’ to ignore errors. (Notethat ignoring encoding errors can lead to data loss.) Other morerarely-used options are also available; see the Python ‘io’ moduledocumentation for ‘io.TextIOWrapper’ for a complete list.

    • newline (str) – (Optional) For text mode only, controls how line endings are handled. It canbe None, ‘’, ‘n’, ‘r’, and ‘rn’. If None, reads use “universalnewline mode” and writes use the system default. See the Python‘io’ module documentation for ‘io.TextIOWrapper’ for details.

    • kwargs – Keyword arguments to pass to the underlying API calls.For both uploads and downloads, the following arguments aresupported:

      • if_generation_match

      • if_generation_not_match

      • if_metageneration_match

      • if_metageneration_not_match

      • timeout

      • retry

      For downloads only, the following additional arguments are supported:

      • raw_download

      For uploads only, the following additional arguments are supported:

      • content_type

      • num_retries

      • predefined_acl

      • checksum

      NOTE:num_retries is supported for backwards-compatibilityreasons only; please useretry with a Retry object orConditionalRetryPolicy instead.

  • Returns

    A ‘BlobReader’ or ‘BlobWriter’ from ‘google.cloud.storage.fileio’, or an ‘io.TextIOWrapper’ around one of those classes, depending on the ‘mode’ argument.

Example

Read from a text blob by using open() as context manager.

Using bucket.get_blob() fetches metadata such as the generation,which prevents race conditions in case the blob is modified.

>>> from google.cloud importstorage>>> client =storage.Client()>>> bucket = client.bucket("bucket-name")
>>> blob = bucket.blob("blob-name.txt")>>> with blob.open("rt") as f:>>>     print(f.read())

property owner()

Retrieve info about the owner of the object.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects

  • Return type

    dict orNoneType

  • Returns

    Mapping of owner’s role/ID, orNone if the blob’s resource has not been loaded from the server.

patch(client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object>)

Sends all changed properties in a PATCH request.

Updates the_properties with the response from the backend.

Ifuser_project is set, bills the API request to that project.

property path()

Getter property for the URL path to this Blob.

  • Return type

    str

  • Returns

    The URL path to this Blob.

static path_helper(bucket_path, blob_name)

Relative URL path for a blob.

  • Parameters

    • bucket_path (str) – The URL path for a bucket.

    • blob_name (str) – The name of the blob.

  • Return type

    str

  • Returns

    The relative URL path forblob_name.

property public_url()

The public URL for this blob.

Usemake_public() to enable anonymous access via the returnedURL.

  • Return type

    string

  • Returns

    The public URL for this blob.

reload(client=None, projection='noAcl', if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.Retry object>)

Reload properties from Cloud Storage.

Ifuser_project is set, bills the API request to that project.

property retention_expiration_time()

Retrieve timestamp at which the object’s retention period expires.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects

  • Return type

    datetime.datetime orNoneType

  • Returns

    Datetime object parsed from RFC3339 valid timestamp, orNone if the property is not set locally.

rewrite(source, token=None, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, if_source_generation_match=None, if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object>)

Rewrite source blob into this one.

Ifuser_project is set on the bucket, bills the API requestto that project.

  • Parameters

    • source (Blob) – blob whose contents will be rewritten into this blob.

    • token (str) – (Optional) Token returned from an earlier, not-completed call torewrite the same source blob. If passed, result will includeupdated status, total bytes written.

    • client (Client) – (Optional) The client to use. If not passed, falls back to theclient stored on the blob’s bucket.

    • if_generation_match (long) – (Optional) SeeUsing if_generation_matchNote that the generation to be matched is that of thedestination blob.

    • if_generation_not_match (long) – (Optional) SeeUsing if_generation_not_matchNote that the generation to be matched is that of thedestination blob.

    • if_metageneration_match (long) – (Optional) SeeUsing if_metageneration_matchNote that the metageneration to be matched is that of thedestination blob.

    • if_metageneration_not_match (long) – (Optional) SeeUsing if_metageneration_not_matchNote that the metageneration to be matched is that of thedestination blob.

    • if_source_generation_match (long) – (Optional) Makes the operation conditional on whether the sourceobject’s generation matches the given value.

    • if_source_generation_not_match (long) – (Optional) Makes the operation conditional on whether the sourceobject’s generation does not match the given value.

    • if_source_metageneration_match (long) – (Optional) Makes the operation conditional on whether the sourceobject’s current metageneration matches the given value.

    • if_source_metageneration_not_match (long) – (Optional) Makes the operation conditional on whether the sourceobject’s current metageneration does not match the given value.

    • timeout (float* or[tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to waitfor the server response. See:Configuring Timeouts

    • retry (google.api_core.retry.Retry* or[google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. See:Configuring Retries

  • Return type

    tuple

  • Returns

    (token, bytes_rewritten, total_bytes), wheretoken is a rewrite token (None if the rewrite is complete),bytes_rewritten is the number of bytes rewritten so far, andtotal_bytes is the total number of bytes to be rewritten.

property self_link()

Retrieve the URI for the object.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects

  • Return type

    str orNoneType

  • Returns

    The self link for the blob orNone if the blob’s resource has not been loaded from the server.

set_iam_policy(policy, client=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object>)

Update the IAM policy for the bucket.

NOTE: Blob- / object-level IAM support does not yet exist and methodscurrently call an internal ACL backend not providing any utilitybeyond the blob’sacl at this time. The API may be enhancedin the future and is currently undocumented. Useacl formanaging object access control.

Ifuser_project is set on the bucket, bills the API requestto that project.

property size()

Size of the object, in bytes.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects

  • Return type

    int orNoneType

  • Returns

    The size of the blob orNone if the blob’s resource has not been loaded from the server.

property storage_class()

Retrieve the storage class for the object.

This can only be set at blob / objectcreation time. If you’dlike to change the storage classafter the blob / object alreadyexists in a bucket, callupdate_storage_class() (which usesrewrite()).

Seehttps://cloud.google.com/storage/docs/storage-classes

property temporary_hold()

Is a temporary hold active on the object?

SeeAPI reference docs.

If the property is not set locally, returnsNone.

  • Return type

    bool orNoneType

test_iam_permissions(permissions, client=None, timeout=60, retry=<google.api_core.retry.Retry object>)

API call: test permissions

NOTE: Blob- / object-level IAM support does not yet exist and methodscurrently call an internal ACL backend not providing any utilitybeyond the blob’sacl at this time. The API may be enhancedin the future and is currently undocumented. Useacl formanaging object access control.

Ifuser_project is set on the bucket, bills the API requestto that project.

property time_created()

Retrieve the timestamp at which the object was created.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects

  • Return type

    datetime.datetime orNoneType

  • Returns

    Datetime object parsed from RFC3339 valid timestamp, orNone if the blob’s resource has not been loaded from the server (seereload()).

property time_deleted()

Retrieve the timestamp at which the object was deleted.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects

  • Return type

    datetime.datetime orNoneType

  • Returns

    Datetime object parsed from RFC3339 valid timestamp, orNone if the blob’s resource has not been loaded from the server (seereload()). If the blob has not been deleted, this will never be set.

update(client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object>)

Sends all properties in a PUT request.

Updates the_properties with the response from the backend.

Ifuser_project is set, bills the API request to that project.

update_storage_class(new_class, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, if_source_generation_match=None, if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object>)

Update blob’s storage class via a rewrite-in-place. This helper willwait for the rewrite to complete before returning, so it may take sometime for large files.

Seehttps://cloud.google.com/storage/docs/per-object-storage-class

Ifuser_project is set on the bucket, bills the API requestto that project.

property updated()

Retrieve the timestamp at which the object was updated.

Seehttps://cloud.google.com/storage/docs/json_api/v1/objects

  • Return type

    datetime.datetime orNoneType

  • Returns

    Datetime object parsed from RFC3339 valid timestamp, orNone if the blob’s resource has not been loaded from the server (seereload()).

upload_from_file(file_obj, rewind=False, size=None, content_type=None, num_retries=None, client=None, predefined_acl=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object>)

Upload the contents of this blob from a file-like object.

The content type of the upload will be determined in orderof precedence:

  • The value passed in to this method (if notNone)

  • The value stored on the current blob

  • The default value (‘application/octet-stream’)

NOTE: The effect of uploading to an existing blob depends on the“versioning” and “lifecycle” policies defined on the blob’sbucket. In the absence of those policies, upload willoverwrite any existing contents.

See theobject versioning andlifecycle API documentsfor details.

Uploading a file with acustomer-supplied encryption key:

from google.cloud.storage importBlobclient =storage.Client(project="my-project")bucket = client.get_bucket("my-bucket")encryption_key = "aa426195405adee2c8081bb9e7e74b19"blob = Blob("secure-data", bucket, encryption_key=encryption_key)with open("my-file", "rb") as my_file:    blob.upload_from_file(my_file)

Theencryption_key should be a str or bytes with a length of atleast 32.

If the size of the data to be uploaded exceeds 8 MB a resumable mediarequest will be used, otherwise the content and the metadata will beuploaded in a single multipart upload request.

For more fine-grained over the upload process, check outgoogle-resumable-media.

Ifuser_project is set on the bucket, bills the API requestto that project.

  • Parameters

    • file_obj (file) – A file handle opened in binary mode for reading.

    • rewind (bool) – If True, seek to the beginning of the file handle before writingthe file to Cloud Storage.

    • size (int) – The number of bytes to be uploaded (which will be read fromfile_obj). If not provided, the upload will be concluded oncefile_obj is exhausted.

    • content_type (str) – (Optional) Type of content being uploaded.

    • num_retries (int) – Number of upload retries. By default, only uploads withif_generation_match set will be retried, as uploads without theargument are not guaranteed to be idempotent. Setting num_retrieswill override this default behavior and guarantee retries even whenif_generation_match is not set. (Deprecated: This argumentwill be removed in a future release.)

    • client (Client) – (Optional) The client to use. If not passed, falls back to theclient stored on the blob’s bucket.

    • predefined_acl (str) – (Optional) Predefined access control list

    • if_generation_match (long) – (Optional) SeeUsing if_generation_match

    • if_generation_not_match (long) – (Optional) SeeUsing if_generation_not_match

    • if_metageneration_match (long) – (Optional) SeeUsing if_metageneration_match

    • if_metageneration_not_match (long) – (Optional) SeeUsing if_metageneration_not_match

    • timeout (float* or[tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to waitfor the server response. See:Configuring Timeouts

    • checksum (str) – (Optional) The type of checksum to compute to verifythe integrity of the object. If the upload is completed in a singlerequest, the checksum will be entirely precomputed and the remoteserver will handle verification and error handling. If the uploadis too large and must be transmitted in multiple requests, thechecksum will be incrementally computed and the client will handleverification and error handling, raisinggoogle.resumable_media.common.DataCorruption on a mismatch andattempting to delete the corrupted file. Supported values are“md5”, “crc32c” and None. The default is None.

    • retry (google.api_core.retry.Retry* or[google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disableretries. A google.api_core.retry.Retry value will enable retries,and the object will define retriable response codes and errors andconfigure backoff and timeout options.

      A google.cloud.storage.retry.ConditionalRetryPolicy value wraps aRetry object and activates it only if certain conditions are met.This class exists to provide safe defaults for RPC calls that arenot technically safe to retry normally (due to potential dataduplication or other side-effects) but become safe to retry if acondition such as if_generation_match is set.

      See the retry.py source code and docstrings in this package(google.cloud.storage.retry) for information on retry types and howto configure them.

      Media operations (downloads and uploads) do not support non-defaultpredicates in a Retry object. The default will always be used. Otherconfiguration changes for Retry objects such as delays and deadlinesare respected.

  • Raises

    GoogleCloudError if the upload response returns an error status.

upload_from_filename(filename, content_type=None, num_retries=None, client=None, predefined_acl=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object>)

Upload this blob’s contents from the content of a named file.

The content type of the upload will be determined in orderof precedence:

  • The value passed in to this method (if notNone)

  • The value stored on the current blob

  • The value given bymimetypes.guess_type

  • The default value (‘application/octet-stream’)

NOTE: The effect of uploading to an existing blob depends on the“versioning” and “lifecycle” policies defined on the blob’sbucket. In the absence of those policies, upload willoverwrite any existing contents.

See theobject versioning andlifecycleAPI documents for details.

Ifuser_project is set on the bucket, bills the API requestto that project.

  • Parameters

    • filename (str) – The path to the file.

    • content_type (str) – (Optional) Type of content being uploaded.

    • client (Client) – (Optional) The client to use. If not passed, falls back to theclient stored on the blob’s bucket.

    • num_retries (int) – Number of upload retries. By default, only uploads withif_generation_match set will be retried, as uploads without theargument are not guaranteed to be idempotent. Setting num_retrieswill override this default behavior and guarantee retries even whenif_generation_match is not set. (Deprecated: This argumentwill be removed in a future release.)

    • predefined_acl (str) – (Optional) Predefined access control list

    • if_generation_match (long) – (Optional) SeeUsing if_generation_match

    • if_generation_not_match (long) – (Optional) SeeUsing if_generation_not_match

    • if_metageneration_match (long) – (Optional) SeeUsing if_metageneration_match

    • if_metageneration_not_match (long) – (Optional) SeeUsing if_metageneration_not_match

    • timeout (float* or[tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to waitfor the server response. See:Configuring Timeouts

    • checksum (str) – (Optional) The type of checksum to compute to verifythe integrity of the object. If the upload is completed in a singlerequest, the checksum will be entirely precomputed and the remoteserver will handle verification and error handling. If the uploadis too large and must be transmitted in multiple requests, thechecksum will be incrementally computed and the client will handleverification and error handling, raisinggoogle.resumable_media.common.DataCorruption on a mismatch andattempting to delete the corrupted file. Supported values are“md5”, “crc32c” and None. The default is None.

    • retry (google.api_core.retry.Retry* or[google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disableretries. A google.api_core.retry.Retry value will enable retries,and the object will define retriable response codes and errors andconfigure backoff and timeout options.

      A google.cloud.storage.retry.ConditionalRetryPolicy value wraps aRetry object and activates it only if certain conditions are met.This class exists to provide safe defaults for RPC calls that arenot technically safe to retry normally (due to potential dataduplication or other side-effects) but become safe to retry if acondition such as if_generation_match is set.

      See the retry.py source code and docstrings in this package(google.cloud.storage.retry) for information on retry types and howto configure them.

      Media operations (downloads and uploads) do not support non-defaultpredicates in a Retry object. The default will always be used. Otherconfiguration changes for Retry objects such as delays and deadlinesare respected.

upload_from_string(data, content_type='text/plain', num_retries=None, client=None, predefined_acl=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object>)

Upload contents of this blob from the provided string.

NOTE: The effect of uploading to an existing blob depends on the“versioning” and “lifecycle” policies defined on the blob’sbucket. In the absence of those policies, upload willoverwrite any existing contents.

See theobject versioning andlifecycleAPI documents for details.

Ifuser_project is set on the bucket, bills the API requestto that project.

  • Parameters

    • data (bytes* or[str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – The data to store in this blob. If the value is text, it will beencoded as UTF-8.

    • content_type (str) – (Optional) Type of content being uploaded. Defaults to'text/plain'.

    • num_retries (int) – Number of upload retries. By default, only uploads withif_generation_match set will be retried, as uploads without theargument are not guaranteed to be idempotent. Setting num_retrieswill override this default behavior and guarantee retries even whenif_generation_match is not set. (Deprecated: This argumentwill be removed in a future release.)

    • client (Client) – (Optional) The client to use. If not passed, falls back to theclient stored on the blob’s bucket.

    • predefined_acl (str) – (Optional) Predefined access control list

    • if_generation_match (long) – (Optional) SeeUsing if_generation_match

    • if_generation_not_match (long) – (Optional) SeeUsing if_generation_not_match

    • if_metageneration_match (long) – (Optional) SeeUsing if_metageneration_match

    • if_metageneration_not_match (long) – (Optional) SeeUsing if_metageneration_not_match

    • timeout (float* or[tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to waitfor the server response. See:Configuring Timeouts

    • checksum (str) – (Optional) The type of checksum to compute to verifythe integrity of the object. If the upload is completed in a singlerequest, the checksum will be entirely precomputed and the remoteserver will handle verification and error handling. If the uploadis too large and must be transmitted in multiple requests, thechecksum will be incrementally computed and the client will handleverification and error handling, raisinggoogle.resumable_media.common.DataCorruption on a mismatch andattempting to delete the corrupted file. Supported values are“md5”, “crc32c” and None. The default is None.

    • retry (google.api_core.retry.Retry* or[google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disableretries. A google.api_core.retry.Retry value will enable retries,and the object will define retriable response codes and errors andconfigure backoff and timeout options.

      A google.cloud.storage.retry.ConditionalRetryPolicy value wraps aRetry object and activates it only if certain conditions are met.This class exists to provide safe defaults for RPC calls that arenot technically safe to retry normally (due to potential dataduplication or other side-effects) but become safe to retry if acondition such as if_generation_match is set.

      See the retry.py source code and docstrings in this package(google.cloud.storage.retry) for information on retry types and howto configure them.

      Media operations (downloads and uploads) do not support non-defaultpredicates in a Retry object. The default will always be used. Otherconfiguration changes for Retry objects such as delays and deadlinesare respected.

property user_project()

Project ID billed for API requests made via this blob.

Derived from bucket’s value.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-05 UTC.