Python

0.02.2

Keys

Create / interact with gcloud storage keys.

class gcloud.storage.key.Key(bucket=None, name=None, properties=None)

Bases: gcloud.storage._helpers._PropertyMixin

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

Key constructor.

Parameters:

• bucket (gcloud.storage.bucket.Bucket) – The bucket to which this key belongs.
• name (string) – The name of the key. This corresponds to the unique path of the object in the bucket.
• 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.

CUSTOM_PROPERTY_ACCESSORS = {'componentCount': 'component_count', 'acl': 'acl', 'generation': 'generation', 'etag': 'etag', 'id': 'id', 'contentDisposition': 'content_disposition', 'updated': 'updated', 'metageneration': 'metageneration', 'contentType': 'content_type', 'size': 'size', 'contentEncoding': 'content_encoding', 'storageClass': 'storage_class', 'cacheControl': 'cache_control', 'name': 'name', 'timeDeleted': 'time_deleted', 'mediaLink': 'media_link', 'selfLink': 'self_link', 'owner': 'owner', 'contentLanguage': 'content_language'}

Map field name -> accessor for fields w/ custom accessors.

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

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

Deletes a key from Cloud Storage.

Return type:Key Returns:The key that was just deleted. Raises:gcloud.storage.exceptions.NotFound (propagated from gcloud.storage.bucket.Bucket.delete_key()).

download_as_string()

Download the contents of this key as a string.

Return type:string Returns:The data stored in this key. Raises:gcloud.storage.exceptions.NotFound

download_to_file(file_obj)

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

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

download_to_filename(filename)

Download the contents of this key into a named file.

Parameters:filename (string) – A filename to be passed to open. Raises:gcloud.storage.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()

Determines whether or not this key exists.

Return type:bool Returns:True if the key exists in Cloud Storage.

classmethod from_dict(key_dict, bucket=None)

Instantiate a Key from data returned by the JSON API.

Parameters:

• key_dict (dict) – A dictionary of data returned from getting an Cloud Storage object.
• bucket (gcloud.storage.bucket.Bucket) – The bucket to which this key belongs (and by proxy, which connection to use).

Return type:

Key

Returns:

A key based on the data provided.

generate_signed_url(expiration, method='GET')

Generates a signed URL for this key.

If you have a key 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 keys, 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

get_contents_as_string()

Download the contents of this key as a string.

Return type:string Returns:The data stored in this key. Raises:gcloud.storage.exceptions.NotFound

get_contents_to_file(file_obj)

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

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

get_contents_to_filename(filename)

Download the contents of this key into a named file.

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

id

Retrieve the ID for the object.

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

Return type:string

make_public()

Make this key 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 Key.

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

public_url

The public URL for this key’s object.

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

rename(new_name)

Renames this key using copy and delete operations.

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

Warning

This method will first duplicate the data and then delete the old key. 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 key. Return type:Key Returns:The newly-copied key.

self_link

Retrieve the URI for the object.

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

Return type:string

set_contents_from_file(file_obj, rewind=False, size=None, content_type=None)

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

Note

The effect of uploading to an existing key depends on the “versioning” and “lifecycle” policies defined on the key’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:

• 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 read from the file handle. If not provided, we’ll try to guess the size using os.fstat()

set_contents_from_filename(filename)

Upload this key’s contents from the content of f named file.

Note

The effect of uploading to an existing key depends on the “versioning” and “lifecycle” policies defined on the key’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 (string) – The path to the file.

set_contents_from_string(data, content_type='text/plain')

Upload contents of this key from the provided string.

Note

The effect of uploading to an existing key depends on the “versioning” and “lifecycle” policies defined on the key’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 (string) – The data to store in this key. Return type:Key Returns:The updated Key object.

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)

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

Note

The effect of uploading to an existing key depends on the “versioning” and “lifecycle” policies defined on the key’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:

• 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 read from the file handle. If not provided, we’ll try to guess the size using os.fstat()

upload_from_filename(filename)

Upload this key’s contents from the content of f named file.

Note

The effect of uploading to an existing key depends on the “versioning” and “lifecycle” policies defined on the key’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 (string) – The path to the file.

upload_from_string(data, content_type='text/plain')

Upload contents of this key from the provided string.

Note

The effect of uploading to an existing key depends on the “versioning” and “lifecycle” policies defined on the key’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 (string) – The data to store in this key. Return type:Key Returns:The updated Key object.