Blobs / Objects#

Create / interact with Google Cloud Storage blobs.

class google.cloud.storage.blob.Blob(name, bucket, chunk_size=None, encryption_key=None)[source]#

Bases: google.cloud.storage._helpers._PropertyMixin

A wrapper around Cloud Storage’s concept of an Object.

Parameters:
  • name (str) – The name of the blob. This corresponds to the unique path of the object in the bucket. If bytes, will be converted to a unicode object. Blob / object names can contain any sequence of valid unicode characters, of length 1-1024 bytes when UTF-8 encoded.
  • bucket (google.cloud.storage.bucket.Bucket) – The bucket to which this blob belongs.
  • chunk_size (int) – The size of a chunk of data whenever iterating (1 MB). This must be a multiple of 256 KB per the API specification.
  • encryption_key (bytes) – Optional 32 byte encryption key for customer-supplied encryption. See https://cloud.google.com/storage/docs/encryption#customer-supplied
acl#

Create our ACL on demand.

cache_control#

HTTP ‘Cache-Control’ header for this object.

See: RFC 7234 and API reference docs.

If the property is not set locally, returns None.

Return type:str or NoneType
chunk_size#

Get the blob’s default chunk size.

Return type:int or NoneType
Returns:The current blob’s chunk size, if it is set.
client#

The client bound to this blob.

component_count#

Number of underlying components that make up this object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:int or NoneType
Returns:The component count (in case of a composed object) or None if the property is not set locally. This property will not be set on objects not created via compose.
compose(sources, client=None)[source]#

Concatenate source blobs into this one.

Parameters:
  • sources (list of Blob) – blobs whose contents will be composed into this blob.
  • client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.
Raises:

ValueError if this blob does not have its content_type set.

content_disposition#

HTTP ‘Content-Disposition’ header for this object.

See: RFC 6266 and API reference docs.

If the property is not set locally, returns None.

Return type:str or NoneType
content_encoding#

HTTP ‘Content-Encoding’ header for this object.

See: RFC 7231 and API reference docs.

If the property is not set locally, returns None.

Return type:str or NoneType
content_language#

HTTP ‘Content-Language’ header for this object.

See: BCP47 and API reference docs.

If the property is not set locally, returns None.

Return type:str or NoneType
content_type#

HTTP ‘Content-Type’ header for this object.

See: RFC 2616 and API reference docs.

If the property is not set locally, returns None.

Return type:str or NoneType
crc32c#

CRC32C checksum for this object.

See: RFC 4960 and API reference docs.

If the property is not set locally, returns None.

Return type:str or NoneType
create_resumable_upload_session(content_type=None, size=None, origin=None, client=None)[source]#

Create a resumable upload session.

Resumable upload sessions allow you to start an upload session from one client and complete the session in another. This method is called by the initiator to set the metadata and limits. The initiator then passes the session URL to the client that will upload the binary data. The client performs a PUT request on the session URL to complete the upload. This process allows untrusted clients to upload to an access-controlled bucket. For more details, see the documentation on signed URLs.

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

  • The value passed in to this method (if not None)
  • 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’s bucket. In the absence of those policies, upload will overwrite any existing contents.

See the object versioning and lifecycle API documents for details.

If encryption_key is set, the blob will be encrypted with a customer-supplied encryption key.

Parameters:
  • size (int) – (Optional). The maximum number of bytes that can be uploaded using this 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-agent that uploads from the given origin. This can be useful when passing the session to a web client.
  • client (Client) – (Optional) The client to use. If not passed, falls back to the client stored on the blob’s bucket.
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.

delete(client=None)[source]#

Deletes a blob from Cloud Storage.

Parameters:client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.
Return type:Blob
Returns:The blob that was just deleted.
Raises:google.cloud.exceptions.NotFound (propagated from google.cloud.storage.bucket.Bucket.delete_blob()).
download_as_string(client=None)[source]#

Download the contents of this blob as a string.

Parameters:client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.
Return type:bytes
Returns:The data stored in this blob.
Raises:google.cloud.exceptions.NotFound
download_to_file(file_obj, client=None)[source]#

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

Note

If the server-set property, media_link, is not yet initialized, makes an additional API request to load it.

Downloading a file that has been encrypted with a customer-supplied encryption key:

    from google.cloud.storage import Blob

    client = 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:
        blob.download_to_file(file_obj)

The encryption_key should be a str or bytes with a length of at least 32.

For more fine-grained over the download process, check out google-resumable-media. For example, this library allows downloading parts of a blob rather than the whole thing.

Parameters:
  • file_obj (file) – A file handle to which to write the blob’s data.
  • client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.
Raises:

google.cloud.exceptions.NotFound

download_to_filename(filename, client=None)[source]#

Download the contents of this blob into a named file.

Parameters:
  • filename (str) – A filename to be passed to open.
  • client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.
Raises:

google.cloud.exceptions.NotFound

etag#

Retrieve the ETag for the object.

See: RFC 2616 (etags) and API reference docs.

Return type:str or NoneType
Returns:The blob etag or None if the property is not set locally.
exists(client=None)[source]#

Determines whether or not this blob exists.

Parameters:client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.
Return type:bool
Returns:True if the blob exists in Cloud Storage.
generate_signed_url(expiration, method='GET', content_type=None, generation=None, response_disposition=None, response_type=None, client=None, credentials=None)[source]#

Generates a signed URL for this blob.

Note

If you are on Google Compute Engine, you can’t generate a signed URL. Follow Issue 922 for updates on this. 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 rather than a GCE service account.

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

This is particularly useful if you don’t want publicly accessible blobs, but don’t want to require users to explicitly log in.

Parameters:
  • expiration (int, long, datetime.datetime, datetime.timedelta) – When the signed URL should expire.
  • method (str) – The HTTP verb that will be used when requesting the URL.
  • content_type (str) – (Optional) The content type of the object referenced by resource.
  • generation (str) – (Optional) A value that indicates which generation of the resource to fetch.
  • response_disposition (str) – (Optional) Content disposition of responses to requests for the signed URL. For example, to enable the signed URL to initiate a file of blog.png, use the value 'attachment; filename=blob.png'.
  • response_type (str) – (Optional) Content type of responses to requests for the signed URL. Used to over-ride the content type of the underlying blob/object.
  • client (Client or NoneType) – (Optional) The client to use. If not passed, falls back to the client stored on the blob’s bucket.
  • credentials (oauth2client.client.OAuth2Credentials or NoneType) – (Optional) The OAuth2 credentials to use to sign the URL. Defaults to the credentials stored on the client used.
Return type:

str

Returns:

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

generation#

Retrieve the generation for the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:int or NoneType
Returns:The generation of the blob or None if the property is not set locally.
get_iam_policy(client=None)[source]#

Retrieve the IAM policy for the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects/getIamPolicy

Parameters:client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current object’s bucket.
Return type:google.cloud.iam.Policy
Returns:the policy instance, based on the resource returned from the getIamPolicy API request.
id#

Retrieve the ID for the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:str or NoneType
Returns:The ID of the blob or None if the property is not set locally.
make_public(client=None)[source]#

Make this blob public giving all users read access.

Parameters:client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.
md5_hash#

MD5 hash for this object.

See: RFC 1321 and API reference docs.

If the property is not set locally, returns None.

Return type:str or NoneType

Retrieve the media download URI for the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:str or NoneType
Returns:The media link for the blob or None if the property is not set locally.
metadata#

Retrieve arbitrary/application specific metadata for the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:dict or NoneType
Returns:The metadata associated with the blob or None if the property is not set locally.
metageneration#

Retrieve the metageneration for the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:int or NoneType
Returns:The metageneration of the blob or None if the property is not set locally.
owner#

Retrieve info about the owner of the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:dict or NoneType
Returns:Mapping of owner’s role/ID. If the property is not set locally, returns None.
patch(client=None)#

Sends all changed properties in a PATCH request.

Updates the _properties with the response from the backend.

Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current object.
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)[source]#

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 for blob_name.

public_url#

The public URL for this blob’s object.

Return type:string
Returns:The public URL for this blob.
reload(client=None)#

Reload properties from Cloud Storage.

Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current object.
rewrite(source, token=None, client=None)[source]#

Rewrite source blob into this one.

Parameters:
  • source (Blob) – blob whose contents will be rewritten into this blob.
  • token (str) – Optional. Token returned from an earlier, not-completed call to rewrite the same source blob. If passed, result will include updated status, total bytes written.
  • client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.
Return type:

tuple

Returns:

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

Retrieve the URI for the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:str or NoneType
Returns:The self link for the blob or None if the property is not set locally.
set_iam_policy(policy, client=None)[source]#

Update the IAM policy for the bucket.

See: https://cloud.google.com/storage/docs/json_api/v1/objects/setIamPolicy

Parameters:
  • policy (google.cloud.iam.Policy) – policy instance used to update bucket’s IAM policy.
  • client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.
Return type:

google.cloud.iam.Policy

Returns:

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

size#

Size of the object, in bytes.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:int or NoneType
Returns:The size of the blob or None if the property is not set locally.
storage_class#

Retrieve the storage class for the object.

This can only be set at blob / object creation time. If you’d like to change the storage class after the blob / object already exists in a bucket, call update_storage_class() (which uses the “storage.objects.rewrite” method).

See: https://cloud.google.com/storage/docs/storage-classes

Return type:str or NoneType
Returns:If set, one of “MULTI_REGIONAL”, “REGIONAL”, “NEARLINE”, “COLDLINE”, “STANDARD”, or “DURABLE_REDUCED_AVAILABILITY”, else None.
test_iam_permissions(permissions, client=None)[source]#

API call: test permissions

See: https://cloud.google.com/storage/docs/json_api/v1/objects/testIamPermissions

Parameters:
  • permissions (list of string) – the permissions to check
  • client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.
Return type:

list of string

Returns:

the permissions returned by the testIamPermissions API request.

time_created#

Retrieve the timestamp at which the object was created.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:datetime.datetime or NoneType
Returns:Datetime object parsed from RFC3339 valid timestamp, or None if the property is not set locally.
time_deleted#

Retrieve the timestamp at which the object was deleted.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:datetime.datetime or NoneType
Returns:Datetime object parsed from RFC3339 valid timestamp, or None if the property is not set locally. If the blob has not been deleted, this will never be set.
update_storage_class(new_class, client=None)[source]#

Update blob’s storage class via a rewrite-in-place.

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

Parameters:
  • new_class (str) – new storage class for the object
  • client (Client) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.
updated#

Retrieve the timestamp at which the object was updated.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:datetime.datetime or NoneType
Returns:Datetime object parsed from RFC3339 valid timestamp, or None if the property is not set locally.
upload_from_file(file_obj, rewind=False, size=None, content_type=None, num_retries=None, client=None)[source]#

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

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

  • The value passed in to this method (if not None)
  • 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’s bucket. In the absence of those policies, upload will overwrite any existing contents.

See the object versioning and lifecycle API documents for details.

Uploading a file with a customer-supplied encryption key:

    from google.cloud.storage import Blob

    client = 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)

The encryption_key should be a str or bytes with a length of at least 32.

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

Parameters:
  • file_obj (file) – A file handle open for reading.
  • rewind (bool) – If True, seek to the beginning of the file handle before writing the file to Cloud Storage.
  • size (int) – The number of bytes to be uploaded (which will be read from file_obj). If not provided, the upload will be concluded once file_obj is exhausted.
  • content_type (str) – Optional type of content being uploaded.
  • num_retries (int) – Number of upload retries. (Deprecated: This argument will be removed in a future release.)
  • client (Client) – (Optional) The client to use. If not passed, falls back to the client stored on the blob’s bucket.
Raises:

GoogleCloudError if the upload response returns an error status.

upload_from_filename(filename, content_type=None, client=None)[source]#

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

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

  • The value passed in to this method (if not None)
  • The value stored on the current blob
  • The value given by mimetypes.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’s bucket. In the absence of those policies, upload will overwrite any existing contents.

See the object versioning and lifecycle API documents for details.

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 the client stored on the blob’s bucket.
upload_from_string(data, content_type='text/plain', client=None)[source]#

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’s bucket. In the absence of those policies, upload will overwrite any existing contents.

See the object versioning and lifecycle API documents for details.

Parameters:
  • data (bytes or str) – The data to store in this blob. If the value is text, it will be encoded as UTF-8.
  • content_type (str) – Optional type of content being uploaded. Defaults to 'text/plain'.
  • client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.