Buckets#

Create / interact with Google Cloud Storage buckets.

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

Bases: google.cloud.storage._helpers._PropertyMixin

A class representing a Bucket on Cloud Storage.

Parameters:
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:

google.cloud.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 google.cloud 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, preserve_acl=True)[source]#

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

Parameters:
  • blob (google.cloud.storage.blob.Blob) – The blob to be copied.
  • destination_bucket (google.cloud.storage.bucket.Bucket) – The bucket into which the blob should be copied.
  • new_name (string) – (optional) the new name for the copied file.
  • client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.
  • preserve_acl (bool) – Optional. Copies ACL from old blob to new blob. Default: True.
Return type:

google.cloud.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 google.cloud.exceptions.Conflict.

This implements “storage.buckets.insert”.

Parameters:client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current 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 google.cloud.exceptions.NotFound. If the bucket is not empty (and force=False), will raise google.cloud.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 (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 google.cloud.exceptions.NotFound.

For example:

>>> from google.cloud.exceptions import NotFound
>>> from google.cloud 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 (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.
Raises:

google.cloud.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:
  • blobs (list of string or google.cloud.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 google.cloud.exceptions.NotFound; otherwise, the exception is propagated.
  • client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.
Raises:

google.cloud.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 (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 google.cloud 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 (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.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 (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 (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 (google.cloud.storage.blob.Blob) – The blob to be renamed.
  • new_name (string) – The new name for this blob.
  • 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.

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.