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:
  • client (google.cloud.storage.client.Client) – A client which holds credentials and project configuration for the bucket (which requires a project).
  • name (str) – The name of the bucket. Bucket names must start and end with a number or letter.
acl#

Create our ACL on demand.

blob(blob_name, chunk_size=None, encryption_key=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 (str) – The name of the blob to be instantiated.
  • chunk_size (int) – The size of a chunk of data whenever iterating (1 MB). This must be a multiple of 256 KB per the API specification.
  • encryption_key (bytes) – Optional 32 byte encryption key for customer-supplied encryption.
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://cloud.google.com/storage/docs/hosting-static-website

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:

    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 (str) – The page to use as the main page of a directory. Typically something like index.html.
  • not_found_page (str) – 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 (str) – (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 or set CORS policies configured for this bucket.

See: http://www.w3.org/TR/cors/ and
https://cloud.google.com/storage/docs/json_api/v1/buckets
Setter:Set CORS policies for this bucket.
Getter:Gets the CORS policies for this bucket.
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 (bool) – 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
    client = storage.Client()
    bucket = client.get_bucket('my-bucket')
    blobs = list(bucket.list_blobs())
    assert len(blobs) > 0
    # [<Blob: my-bucket, my-file.txt>]
    bucket.delete_blob('my-file.txt')
    try:
        bucket.delete_blob('doesnt-exist')
    except NotFound:
        pass
Parameters:
  • blob_name (str) – 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 delete_blob() to delete each individual blob.

Parameters:
  • blobs (list) – A list of Blob-s or blob names to delete.
  • on_error (callable) – (Optional) Takes single argument: blob. Called called once for each blob raising NotFound; otherwise, the exception is propagated.
  • client (Client) – (Optional) The client to use. If not passed, falls back to the client stored on the current bucket.
Raises:

NotFound (if on_error is not passed).

disable_logging()[source]#

Disable access logging for this bucket.

See: https://cloud.google.com/storage/docs/access-logs#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/access-logs

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

Retrieve the ETag for the bucket.

See: https://tools.ietf.org/html/rfc2616#section-3.11 and
https://cloud.google.com/storage/docs/json_api/v1/buckets
Return type:str 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:bool
Returns:True if the bucket exists in Cloud Storage.
generate_upload_policy(conditions, expiration=None, client=None)[source]#

Create a signed upload policy for uploading objects.

This method generates and signs a policy document. You can use policy documents to allow visitors to a website to upload files to Google Cloud Storage without giving them direct write access.

For example:

    bucket = client.bucket('my-bucket')
    conditions = [
        ['starts-with', '$key', ''],
        {'acl': 'public-read'}]

    policy = bucket.generate_upload_policy(conditions)

    # Generate an upload form using the form fields.
    policy_fields = ''.join(
        '<input type="hidden" name="{key}" value="{value}">'.format(
            key=key, value=value)
        for key, value in policy.items()
    )

    upload_form = (
        '<form action="http://{bucket_name}.storage.googleapis.com"'
        '   method="post" enctype="multipart/form-data">'
        '<input type="text" name="key" value="my-test-key">'
        '<input type="hidden" name="bucket" value="{bucket_name}">'
        '<input type="hidden" name="acl" value="public-read">'
        '<input name="file" type="file">'
        '<input type="submit" value="Upload">'
        '{policy_fields}'
        '</form>').format(bucket_name=bucket.name, policy_fields=policy_fields)

    print(upload_form)
Parameters:
  • expiration (datetime) – Optional expiration in UTC. If not specified, the policy will expire in 1 hour.
  • conditions (list) – A list of conditions as described in the policy documents documentation.
  • client (Client) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.
Return type:

dict

Returns:

A dictionary of (form field name, form field value) of form fields that should be added to your HTML upload form in order to attach the signature.

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

Get a blob object by name.

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

    client = storage.Client()
    bucket = client.get_bucket('my-bucket')
    assert isinstance(bucket.get_blob('/path/to/blob.txt'), Blob)
    # <Blob: my-bucket, /path/to/blob.txt>
    assert not bucket.get_blob('/does-not-exist.txt')
    # None
Parameters:
  • blob_name (str) – 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_iam_policy(client=None)[source]#

Retrieve the IAM policy for the bucket.

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

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:google.cloud.iam.Policy
Returns:the policy instance, based on the resource returned from the getIamPolicy API request.
get_logging()[source]#

Return info about access logging for this bucket.

See: https://cloud.google.com/storage/docs/access-logs#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:str 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 (int) – (Optional) Maximum number of blobs to return.
  • page_token (str) – (Optional) Opaque marker for the next “page” of blobs. If not passed, will return the first page of blobs.
  • prefix (str) – (Optional) prefix used to filter blobs.
  • delimiter (str) – (Optional) Delimiter, used with prefix to emulate hierarchy.
  • versions (bool) – (Optional) Whether object versions should be returned as separate blobs.
  • projection (str) – (Optional) If used, must be ‘full’ or ‘noAcl’. Defaults to 'noAcl'. Specifies the set of properties to return.
  • fields (str) – (Optional) 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) – (Optional) The client to use. If not passed, falls back to the client stored on the current bucket.
Return type:

Iterator

Returns:

Iterator of all Blob in this bucket matching the arguments.

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/bucket-locations

If the property is not set locally, returns None.

Return type:str 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 (bool) – If True, this will make all blobs inside the bucket public as well.
  • future (bool) – 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:int 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.
patch(client=None)#

Sends all changed properties in a PATCH request.

Updates the _properties with the response from the backend.

Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current object.
path#

The URL path to this bucket.

static path_helper(bucket_name)[source]#

Relative URL path for a bucket.

Parameters:bucket_name (str) – The bucket name in the path.
Return type:str
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:int or NoneType
Returns:The project number that owns the bucket or None if the property is not set locally.
reload(client=None)#

Reload properties from Cloud Storage.

Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current object.
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 (str) – 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:str or NoneType
Returns:The self link for the bucket or None if the property is not set locally.
set_iam_policy(policy, client=None)[source]#

Update the IAM policy for the bucket.

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

Parameters:
  • policy (google.cloud.iam.Policy) – policy instance used to update bucket’s IAM policy.
  • 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.iam.Policy

Returns:

the policy instance, based on the resource returned from the setIamPolicy API request.

storage_class#

Retrieve the storage class for the bucket.

See: https://cloud.google.com/storage/docs/storage-classes

Return type:str or NoneType
Returns:If set, one of “MULTI_REGIONAL”, “REGIONAL”, “NEARLINE”, “COLDLINE”, “STANDARD”, or “DURABLE_REDUCED_AVAILABILITY”, else None.
test_iam_permissions(permissions, client=None)[source]#

API call: test permissions

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

Parameters:
  • permissions (list of string) – the permissions to check
  • client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.
Return type:

list of string

Returns:

the permissions returned by the testIamPermissions API request.

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:bool
Returns:True if enabled, else False.