Buckets#

Create / interact with gcloud storage buckets.

class gcloud.storage.bucket.Bucket(client, name=None)[source]#

Bases: gcloud.storage._helpers._PropertyMixin

A class representing a Bucket on Cloud Storage.

Parameters:	client (`gcloud.storage.client.Client`) – A client which holds credentials and project configuration for the bucket (which requires a project). name (string) – The name of the bucket.

acl#: Create our ACL on demand.

blob(blob_name, chunk_size=None)[source]#

Factory constructor for blob object.

Note

This will not make an HTTP request; it simply instantiates a blob object owned by this bucket.

Parameters:	blob_name (string) – The name of the blob to be instantiated. chunk_size (integer) – The size of a chunk of data whenever iterating (1 MB). This must be a multiple of 256 KB per the API specification.
Return type:	`gcloud.storage.blob.Blob`
Returns:	The blob object created.

client#: The client bound to this bucket.

configure_website(main_page_suffix=None, not_found_page=None)[source]#

Configure website-related properties.

See: https://developers.google.com/storage/docs/website-configuration

Note

This (apparently) only works if your bucket name is a domain name (and to do that, you need to get approved somehow...).

If you want this bucket to host a website, just provide the name of an index page and a page to use when a blob isn’t found:

>>> from gcloud import storage
>>> client = storage.Client()
>>> bucket = client.get_bucket(bucket_name)
>>> bucket.configure_website('index.html', '404.html')

You probably should also make the whole bucket public:

>>> bucket.make_public(recursive=True, future=True)

This says: “Make the bucket public, and all the stuff already in the bucket, and anything else I add to the bucket. Just make it all public.”

Parameters:	main_page_suffix (string) – The page to use as the main page of a directory. Typically something like index.html. not_found_page (string) – The file to use when a page isn’t found.

copy_blob(blob, destination_bucket, new_name=None, client=None)[source]#

Copy the given blob to the given bucket, optionally with a new name.

Parameters:	blob (`gcloud.storage.blob.Blob`) – The blob to be copied. destination_bucket (`gcloud.storage.bucket.Bucket`) – The bucket into which the blob should be copied. new_name (string) – (optional) the new name for the copied file. client (`gcloud.storage.client.Client` or `NoneType`) – Optional. The client to use. If not passed, falls back to the `client` stored on the current bucket.
Return type:	`gcloud.storage.blob.Blob`
Returns:	The new Blob.

cors#

Retrieve CORS policies configured for this bucket.

See: http://www.w3.org/TR/cors/ and: https://cloud.google.com/storage/docs/json_api/v1/buckets

Return type:	list of dictionaries
Returns:	A sequence of mappings describing each CORS policy.

create(client=None)[source]#

Creates current bucket.

If the bucket already exists, will raise gcloud.exceptions.Conflict.

This implements “storage.buckets.insert”.

Parameters:	client (`gcloud.storage.client.Client` or `NoneType`) – Optional. The client to use. If not passed, falls back to the `client` stored on the current bucket.
Return type:	`gcloud.storage.bucket.Bucket`
Returns:	The newly created bucket.

default_object_acl#: Create our defaultObjectACL on demand.

delete(force=False, client=None)[source]#

Delete this bucket.

The bucket must be empty in order to submit a delete request. If force=True is passed, this will first attempt to delete all the objects / blobs in the bucket (i.e. try to empty the bucket).

If the bucket doesn’t exist, this will raise gcloud.exceptions.NotFound. If the bucket is not empty (and force=False), will raise gcloud.exceptions.Conflict.

If force=True and the bucket contains more than 256 objects / blobs this will cowardly refuse to delete the objects (or the bucket). This is to prevent accidental bucket deletion and to prevent extremely long runtime of this method.

Parameters:	force (boolean) – If True, empties the bucket’s objects then deletes it. client (`gcloud.storage.client.Client` or `NoneType`) – Optional. The client to use. If not passed, falls back to the `client` stored on the current bucket.
Raises:	`ValueError` if `force` is `True` and the bucket contains more than 256 objects / blobs.

delete_blob(blob_name, client=None)[source]#

Deletes a blob from the current bucket.

If the blob isn’t found (backend 404), raises a gcloud.exceptions.NotFound.

For example:

>>> from gcloud.exceptions import NotFound
>>> from gcloud import storage
>>> client = storage.Client()
>>> bucket = client.get_bucket('my-bucket')
>>> print bucket.list_blobs()
[<Blob: my-bucket, my-file.txt>]
>>> bucket.delete_blob('my-file.txt')
>>> try:
...   bucket.delete_blob('doesnt-exist')
... except NotFound:
...   pass

Parameters:	blob_name (string) – A blob name to delete. client (`gcloud.storage.client.Client` or `NoneType`) – Optional. The client to use. If not passed, falls back to the `client` stored on the current bucket.
Raises:	`gcloud.exceptions.NotFound` (to suppress the exception, call `delete_blobs`, passing a no-op `on_error` callback, e.g.: >>> bucket.delete_blobs([blob], on_error=lambda blob: None)

delete_blobs(blobs, on_error=None, client=None)[source]#

Deletes a list of blobs from the current bucket.

Uses Bucket.delete_blob() to delete each individual blob.

Parameters:

Parameters:	blobs (list of string or `gcloud.storage.blob.Blob`) – A list of blob names or Blob objects to delete. on_error (a callable taking (blob)) – If not `None`, called once for each blob raising `gcloud.exceptions.NotFound`; otherwise, the exception is propagated. client (`gcloud.storage.client.Client` or `NoneType`) – Optional. The client to use. If not passed, falls back to the `client` stored on the current bucket.
Raises:	`gcloud.exceptions.NotFound` (if on_error is not passed).

blobs (list of string or gcloud.storage.blob.Blob) – A list of blob names or Blob objects to delete.
on_error (a callable taking (blob)) – If not None, called once for each blob raising gcloud.exceptions.NotFound; otherwise, the exception is propagated.
client (gcloud.storage.client.Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.

Raises:

gcloud.exceptions.NotFound (if on_error is not passed).

disable_logging()[source]#

Disable access logging for this bucket.

See: https://cloud.google.com/storage/docs/accesslogs#disabling

disable_website()[source]#

Disable the website configuration for this bucket.

This is really just a shortcut for setting the website-related attributes to None.

enable_logging(bucket_name, object_prefix='')[source]#

Enable access logging for this bucket.

See: https://cloud.google.com/storage/docs/accesslogs#delivery

Parameters:	bucket_name (string) – name of bucket in which to store access logs object_prefix (string) – prefix for access log filenames

etag#

Retrieve the ETag for the bucket.

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

Return type:	string or `NoneType`
Returns:	The bucket etag or `None` if the property is not set locally.

exists(client=None)[source]#

Determines whether or not this bucket exists.

Parameters:	client (`gcloud.storage.client.Client` or `NoneType`) – Optional. The client to use. If not passed, falls back to the `client` stored on the current bucket.
Return type:	boolean
Returns:	True if the bucket exists in Cloud Storage.

get_blob(blob_name, client=None)[source]#

Get a blob object by name.

This will return None if the blob doesn’t exist:

>>> from gcloud import storage
>>> client = storage.Client()
>>> bucket = client.get_bucket('my-bucket')
>>> print bucket.get_blob('/path/to/blob.txt')
<Blob: my-bucket, /path/to/blob.txt>
>>> print bucket.get_blob('/does-not-exist.txt')
None

Parameters:	blob_name (string) – The name of the blob to retrieve. client (`gcloud.storage.client.Client` or `NoneType`) – Optional. The client to use. If not passed, falls back to the `client` stored on the current bucket.
Return type:	`gcloud.storage.blob.Blob` or None
Returns:	The blob object if it exists, otherwise None.

get_logging()[source]#

Return info about access logging for this bucket.

See: https://cloud.google.com/storage/docs/accesslogs#status

Return type:	dict or None
Returns:	a dict w/ keys, `logBucket` and `logObjectPrefix` (if logging is enabled), or None (if not).

id#

Retrieve the ID for the bucket.

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

Return type:	string or `NoneType`
Returns:	The ID of the bucket or `None` if the property is not set locally.

lifecycle_rules#

Lifecycle rules configured for this bucket.

See: https://cloud.google.com/storage/docs/lifecycle and: https://cloud.google.com/storage/docs/json_api/v1/buckets

Return type:	list(dict)
Returns:	A sequence of mappings describing each lifecycle rule.

list_blobs(max_results=None, page_token=None, prefix=None, delimiter=None, versions=None, projection='noAcl', fields=None, client=None)[source]#

Return an iterator used to find blobs in the bucket.

Parameters:	max_results (integer or `NoneType`) – maximum number of blobs to return. page_token (string) – opaque marker for the next “page” of blobs. If not passed, will return the first page of blobs. prefix (string or `NoneType`) – optional prefix used to filter blobs. delimiter (string or `NoneType`) – optional delimter, used with `prefix` to emulate hierarchy. versions (boolean or `NoneType`) – whether object versions should be returned as separate blobs. projection (string or `NoneType`) – If used, must be ‘full’ or ‘noAcl’. Defaults to ‘noAcl’. Specifies the set of properties to return. fields (string or `NoneType`) – Selector specifying which fields to include in a partial response. Must be a list of fields. For example to get a partial response with just the next page token and the language of each blob returned: ‘items/contentLanguage,nextPageToken’ client (`gcloud.storage.client.Client` or `NoneType`) – Optional. The client to use. If not passed, falls back to the `client` stored on the current bucket.
Return type:	`_BlobIterator`.
Returns:	An iterator of blobs.

location#

Retrieve location configured for this bucket.

See: https://cloud.google.com/storage/docs/json_api/v1/buckets and https://cloud.google.com/storage/docs/concepts-techniques#specifyinglocations

If the property is not set locally, returns None.

Return type:	string or `NoneType`

make_public(recursive=False, future=False, client=None)[source]#

Make a bucket public.

If recursive=True and the bucket contains more than 256 objects / blobs this will cowardly refuse to make the objects public. This is to prevent extremely long runtime of this method.

Parameters:	recursive (boolean) – If True, this will make all blobs inside the bucket public as well. future (boolean) – If True, this will make all objects created in the future public as well. client (`gcloud.storage.client.Client` or `NoneType`) – Optional. The client to use. If not passed, falls back to the `client` stored on the current bucket.

metageneration#

Retrieve the metageneration for the bucket.

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

Return type:	integer or `NoneType`
Returns:	The metageneration of the bucket or `None` if the property is not set locally.

owner#

Retrieve info about the owner of the bucket.

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

Return type:	dict or `NoneType`
Returns:	Mapping of owner’s role/ID. If the property is not set locally, returns `None`.

path#: The URL path to this bucket.

static path_helper(bucket_name)[source]#

Relative URL path for a bucket.

Parameters:	bucket_name (string) – The bucket name in the path.
Return type:	string
Returns:	The relative URL path for `bucket_name`.

project_number#

Retrieve the number of the project to which the bucket is assigned.

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

Return type:	integer or `NoneType`
Returns:	The project number that owns the bucket or `None` if the property is not set locally.

rename_blob(blob, new_name, client=None)[source]#

Rename the given 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:	blob (`gcloud.storage.blob.Blob`) – The blob to be renamed. new_name (string) – The new name for this blob. client (`gcloud.storage.client.Client` or `NoneType`) – Optional. The client to use. If not passed, falls back to the `client` stored on the current bucket.
Return type:	`Blob`
Returns:	The newly-renamed blob.

self_link#

Retrieve the URI for the bucket.

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

Return type:	string or `NoneType`
Returns:	The self link for the bucket or `None` if the property is not set locally.

storage_class#

Retrieve the storage class for the bucket.

See: https://cloud.google.com/storage/docs/storage-classes https://cloud.google.com/storage/docs/nearline-storage https://cloud.google.com/storage/docs/durable-reduced-availability

Return type:	string or `NoneType`
Returns:	If set, one of “STANDARD”, “NEARLINE”, or “DURABLE_REDUCED_AVAILABILITY”, else `None`.

time_created#

Retrieve the timestamp at which the bucket was created.

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

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

versioning_enabled#

Is versioning enabled for this bucket?

See: https://cloud.google.com/storage/docs/object-versioning for details.

Return type:	boolean
Returns:	True if enabled, else False.