Class Blob (1.18.0)

Version 1.18.0

• 2.19.0 (latest)
• 2.17.0
• 2.16.0
• 2.15.0
• 2.14.0
• 2.13.0
• 2.12.0
• 2.11.0
• 2.10.0
• 2.9.0
• 2.8.0
• 2.7.0
• 2.6.0
• 2.5.0
• 2.4.0
• 2.3.0
• 2.2.1
• 2.1.0
• 2.0.0
• 1.44.0
• 1.43.0
• 1.42.3
• 1.41.1
• 1.40.0
• 1.39.0
• 1.38.0
• 1.37.1
• 1.36.2
• 1.35.1
• 1.34.0
• 1.33.0
• 1.32.0
• 1.31.2
• 1.30.0
• 1.29.0
• 1.28.1
• 1.27.0
• 1.26.0
• 1.25.0
• 1.24.1
• 1.23.0
• 1.22.0
• 1.21.0
• 1.20.0
• 1.19.0
• 1.18.0
• 1.17.0

Blob(
    name,
    bucket,
    chunk_size=None,
    encryption_key=None,
    kms_key_name=None,
    generation=None,
)

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

Parameters
Name	Description
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	Bucket The bucket to which this blob belongs.
chunk_size	int The size of a chunk of data whenever iterating (in bytes). 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.
kms_key_name	str Optional resource name of Cloud KMS key used to encrypt the blob's contents.

Properties

acl

Create our ACL on demand.

cache_control

Scalar property getter.

chunk_size

Get the blob's default chunk size.

Returns
Type	Description
int or NoneType	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

Returns
Type	Description
int or NoneType	The component count (in case of a composed object) or None if the blob's resource has not been loaded from the server. This property will not be set on objects not created via compose.

content_disposition

Scalar property getter.

content_encoding

Scalar property getter.

content_language

Scalar property getter.

content_type

Scalar property getter.

crc32c

Scalar property getter.

etag

Retrieve the ETag for the object.

See RFC 2616 (etags) and API reference docs.

Returns
Type	Description
str or NoneType	The blob etag or None if the blob's resource has not been loaded from the server. .. _RFC 2616 (etags): https://tools.ietf.org/html/rfc2616#section-3.11

event_based_hold

Scalar property getter.

generation

Retrieve the generation for the object.

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

Returns
Type	Description
int or NoneType	The generation of the blob or None if the blob's resource has not been loaded from the server.

Methods

compose

compose(sources, client=None)

Concatenate source blobs into this one.

If user_project is set on the bucket, bills the API request to that project.

Parameters
Name	Description
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.

create_resumable_upload_session

create_resumable_upload_session(
    content_type=None, size=None, origin=None, client=None
)

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_.

.. _documentation on signed URLs: https://cloud.google.com/storage/ docs/access-control/signed-urls#signing-resumable

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

• The value passed in to this method (if not :data: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 <https://cloud.google.com/storage/docs/object-versioning> and lifecycle <https://cloud.google.com/storage/docs/lifecycle> API documents for details.

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

If user_project is set on the bucket, bills the API request to that project.

Parameters
Name	Description
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.

Exceptions
Type	Description
GoogleCloudError	if the session creation response returns an error status.

Returns
Type	Description
str	The resumable upload session URL. The upload can be completed by making an HTTP PUT request with the file's contents.

delete

delete(client=None)

Deletes a blob from Cloud Storage.

If user_project is set on the bucket, bills the API request to that project.

Parameter
Name	Description
client	Client or NoneType Optional. The client to use. If not passed, falls back to the client stored on the blob's bucket.

Exceptions
Type	Description
NotFound	(propagated from delete_blob).

Returns
Type	Description
Blob	The blob that was just deleted.

download_as_string

download_as_string(client=None, start=None, end=None)

Download the contents of this blob as a string.

If user_project is set on the bucket, bills the API request to that project.

Parameters
Name	Description
client	Client or NoneType Optional. The client to use. If not passed, falls back to the client 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.

Exceptions
Type	Description
NotFound

Returns
Type	Description
bytes	The data stored in this blob.

download_to_file

download_to_file(file_obj, client=None, start=None, end=None)

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.

.. literalinclude:: snippets.py :start-after: [START download_to_file] :end-before: [END download_to_file] :dedent: 4

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

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

If user_project is set on the bucket, bills the API request to that project.

Parameters
Name	Description
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.
start	int Optional, the first byte in a range to be downloaded.
end	int Optional, The last byte in a range to be downloaded.

Exceptions
Type	Description
NotFound

download_to_filename

download_to_filename(filename, client=None, start=None, end=None)

Download the contents of this blob into a named file.

If user_project is set on the bucket, bills the API request to that project.

Parameters
Name	Description
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.
start	int Optional, the first byte in a range to be downloaded.
end	int Optional, The last byte in a range to be downloaded.

Exceptions
Type	Description
NotFound

exists

exists(client=None)

Determines whether or not this blob exists.

If user_project is set on the bucket, bills the API request to that project.

Parameter
Name	Description
client	Client or NoneType Optional. The client to use. If not passed, falls back to the client stored on the blob's bucket.

Returns
Type	Description
bool	True if the blob exists in Cloud Storage.

generate_signed_url

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,
)

Generates a signed URL for this blob.

Note: If you are on Google Compute Engine, you can't generate a signed URL using GCE service account. Follow Issue 50_ 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
Name	Description
expiration	Union[Integer, datetime.datetime, datetime.timedelta] Point in time when the signed URL should expire.
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 by resource.
content_type	str (Optional) The content type of the object referenced by resource.
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.
generation	str (Optional) A value that indicates which generation of the resource to fetch.
headers	dict (Optional) Additional HTTP headers to be included as part of the signed URLs. See: https://cloud.google.com/storage/docs/xml-api/reference-headers Requests using the signed URL must pass the specified header (name and value) with each request for the URL.
query_parameters	dict (Optional) Additional query paramtersto be included as part of the signed URLs. See: https://cloud.google.com/storage/docs/xml-api/reference-headers#query
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.
version	str (Optional) The version of signed credential to create. Must be one of 'v2' 'v4'.

Exceptions
Type	Description
`ValueError	when version is invalid.
`TypeError	when expiration is not a valid type.
`AttributeError	if credentials is not an instance of google.auth.credentials.Signing.

Returns
Type	Description
str	A signed URL you can use to access the resource until expiration.