Python

Version History (0.4.3)

Report an Issue

Blobs / Objects#

Create / interact with Google Cloud Storage blobs.

class gcloud.storage.blob.Blob(name, bucket=None, properties=None)[source]#

Bases: gcloud.storage._helpers._PropertyMixin

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

Parameters:	name (string) – The name of the blob. This corresponds to the unique path of the object in the bucket. bucket (`gcloud.storage.bucket.Bucket`) – The bucket to which this blob belongs. Required, unless the implicit default bucket has been set. properties (dict) – All the other data provided by Cloud Storage.

CHUNK_SIZE = 1048576#

The size of a chunk of data whenever iterating (1 MB).

This must be a multiple of 256 KB per the API specification.

acl#: Create our ACL on demand.

cache_control#

HTTP ‘Cache-Control’ header for this object.

See: https://tools.ietf.org/html/rfc7234#section-5.2 and: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	string

component_count#

Number of underlying components that make up this object.

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

Return type:	integer

connection#

Getter property for the connection to use with this Blob.

Return type:	`gcloud.storage.connection.Connection` or None
Returns:	The connection to use, or None if no connection is set.

content_disposition#

HTTP ‘Content-Disposition’ header for this object.

See: https://tools.ietf.org/html/rfc6266 and: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	string

content_encoding#

HTTP ‘Content-Encoding’ header for this object.

See: https://tools.ietf.org/html/rfc7231#section-3.1.2.2 and: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	string

content_language#

HTTP ‘Content-Language’ header for this object.

See: http://tools.ietf.org/html/bcp47 and: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	string

content_type#

HTTP ‘Content-Type’ header for this object.

See: https://tools.ietf.org/html/rfc2616#section-14.17 and: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	string

crc32c#

CRC32C checksum for this object.

See: http://tools.ietf.org/html/rfc4960#appendix-B and: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	string

delete()[source]#

Deletes a blob from Cloud Storage.

Return type:	`Blob`
Returns:	The blob that was just deleted.
Raises:	`gcloud.exceptions.NotFound` (propagated from `gcloud.storage.bucket.Bucket.delete_blob()`).

download_as_string()[source]#

Download the contents of this blob as a string.

Return type:	bytes
Returns:	The data stored in this blob.
Raises:	`gcloud.exceptions.NotFound`

download_to_file(file_obj)[source]#

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

Parameters:	file_obj (file) – A file handle to which to write the blob’s data.
Raises:	`gcloud.exceptions.NotFound`

download_to_filename(filename)[source]#

Download the contents of this blob into a named file.

Parameters:	filename (string) – A filename to be passed to `open`.
Raises:	`gcloud.exceptions.NotFound`

etag#

Retrieve the ETag for the object.

See: http://tools.ietf.org/html/rfc2616#section-3.11 and: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	string

exists()[source]#

Determines whether or not this blob exists.

Return type:	boolean
Returns:	True if the blob exists in Cloud Storage.

generate_signed_url(expiration, method='GET')[source]#

Generates a signed URL for this blob.

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 (string) – The HTTP verb that will be used when requesting the URL.
Return type:	string
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:	integer

id#

Retrieve the ID for the object.

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

Return type:	string

make_public()[source]#

Make this blob public giving all users read access.

Returns:	The current object.

md5_hash#

MD5 hash for this object.

See: http://tools.ietf.org/html/rfc4960#appendix-B and: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	string

media_link#

Retrieve the media download URI for the object.

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

Return type:	string

metadata#

Retrieve arbitrary/application specific metadata for the object.

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

Return type:	dict

metageneration#

Retrieve the metageneration for the object.

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

Return type:	integer

owner#

Retrieve info about the owner of the object.

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

Return type:	dict
Returns:	mapping of owner’s role/ID.

path#

Getter property for the URL path to this Blob.

Return type:	string
Returns:	The URL path to this Blob.

public_url#

The public URL for this blob’s object.

Return type:	string
Returns:	The public URL for this blob.

rename(new_name)[source]#

Renames this blob using copy and delete operations.

Effectively, copies blob to the same bucket with a new name, then deletes the blob.

Warning

This method will first duplicate the data and then delete the old blob. This means that with very large objects renaming could be a very (temporarily) costly or a very slow operation.

Parameters:	new_name (string) – The new name for this blob.
Return type:	`Blob`
Returns:	The newly-copied blob.

self_link#

Retrieve the URI for the object.

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

Return type:	string

size#

Size of the object, in bytes.

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

Return type:	integer

storage_class#

Retrieve the storage class for the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects and https://cloud.google.com/storage/docs/durable-reduced-availability#_DRA_Bucket

Return type:	string
Returns:	Currently one of “STANDARD”, “DURABLE_REDUCED_AVAILABILITY”

time_deleted#

Retrieve the timestamp at which the object was deleted.

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

Return type:	string or None
Returns:	timestamp in RFC 3339 format, or None if the object has a “live” version.

updated#

Retrieve the timestamp at which the object was updated.

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

Return type:	string
Returns:	timestamp in RFC 3339 format.

upload_from_file(file_obj, rewind=False, size=None, content_type=None, num_retries=6)[source]#

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

The content type of the upload will either be - The value passed in to the function (if any) - The value stored on the current blob - The default value of ‘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:

Parameters:	file_obj (file) – A file handle open for reading. rewind (boolean) – If True, seek to the beginning of the file handle before writing the file to Cloud Storage. size (int) – The number of bytes to read from the file handle. If not provided, we’ll try to guess the size using `os.fstat()` content_type (string or `NoneType`) – Optional type of content being uploaded. num_retries (integer) – Number of upload retries. Defaults to 6.

file_obj (file) – A file handle open for reading.
rewind (boolean) – If True, seek to the beginning of the file handle before writing the file to Cloud Storage.
size (int) – The number of bytes to read from the file handle. If not provided, we’ll try to guess the size using os.fstat()
content_type (string or NoneType) – Optional type of content being uploaded.
num_retries (integer) – Number of upload retries. Defaults to 6.

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

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

The content type of the upload will either be - The value passed in to the function (if any) - The value stored on the current blob - The value given by mimetypes.guess_type

Note

See the object versioning and lifecycle API documents for details.

Parameters:	filename (string) – The path to the file. content_type (string or `NoneType`) – Optional type of content being uploaded.

upload_from_string(data, content_type='text/plain')[source]#

Upload contents of this blob from the provided string.

Note

See the object versioning and lifecycle API documents for details.

Parameters:	data (bytes or text) – The data to store in this blob. If the value is text, it will be encoded as UTF-8.