Storage Client#

Client for interacting with the Google Cloud Storage API.

class google.cloud.storage.client.Client(project=None, credentials=None, http=None)[source]#

Bases: google.cloud.client.ClientWithProject

Client to bundle configuration needed for API requests.

Parameters:
  • project (str) – the project which the client acts on behalf of. Will be passed when creating a topic. If not passed, falls back to the default inferred from the environment.
  • credentials (Credentials) – (Optional) The OAuth2 Credentials to use for this client. If not passed (and if no http object is passed), falls back to the default inferred from the environment.
  • http (Http) – (Optional) HTTP object to make requests. Can be any object that defines request() with the same interface as request(). If not passed, an http object is created that is bound to the credentials for the current object.
SCOPE = ('https://www.googleapis.com/auth/devstorage.full_control', 'https://www.googleapis.com/auth/devstorage.read_only', 'https://www.googleapis.com/auth/devstorage.read_write')#

The scopes required for authenticating as a Cloud Storage consumer.

batch()[source]#

Factory constructor for batch object.

Note

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

Return type:google.cloud.storage.batch.Batch
Returns:The batch object created.
bucket(bucket_name)[source]#

Factory constructor for bucket object.

Note

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

Parameters:bucket_name (str) – The name of the bucket to be instantiated.
Return type:google.cloud.storage.bucket.Bucket
Returns:The bucket object created.
create_bucket(bucket_name)[source]#

Create a new bucket.

For example:

    bucket = client.create_bucket('my-bucket')
    assert isinstance(bucket, Bucket)
    # <Bucket: my-bucket>

This implements “storage.buckets.insert”.

If the bucket already exists, will raise google.cloud.exceptions.Conflict.

Parameters:bucket_name (str) – The bucket name to create.
Return type:google.cloud.storage.bucket.Bucket
Returns:The newly created bucket.
current_batch#

Currently-active batch.

Return type:google.cloud.storage.batch.Batch or NoneType (if no batch is active).
Returns:The batch at the top of the batch stack.
get_bucket(bucket_name)[source]#

Get a bucket by name.

If the bucket isn’t found, this will raise a google.cloud.storage.exceptions.NotFound.

For example:

    try:
        bucket = client.get_bucket('my-bucket')
    except google.cloud.exceptions.NotFound:
        print('Sorry, that bucket does not exist!')

This implements “storage.buckets.get”.

Parameters:bucket_name (str) – The name of the bucket to get.
Return type:google.cloud.storage.bucket.Bucket
Returns:The bucket matching the name provided.
Raises:google.cloud.exceptions.NotFound
list_buckets(max_results=None, page_token=None, prefix=None, projection='noAcl', fields=None)[source]#

Get all buckets in the project associated to the client.

This will not populate the list of blobs available in each bucket.

    for bucket in client.list_buckets():
        print(bucket)

This implements “storage.buckets.list”.

Parameters:
  • max_results (int) – Optional. Maximum number of buckets to return.
  • page_token (str) – Optional. Opaque marker for the next “page” of buckets. If not passed, will return the first page of buckets.
  • prefix (str) – Optional. Filter results to buckets whose names begin with this prefix.
  • projection (str) – (Optional) Specifies the set of properties to return. If used, must be ‘full’ or ‘noAcl’. Defaults to ‘noAcl’.
  • 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 bucket returned: ‘items/id,nextPageToken’
Return type:

Iterator

Returns:

Iterator of all Bucket belonging to this project.

lookup_bucket(bucket_name)[source]#

Get a bucket by name, returning None if not found.

You can use this if you would rather check for a None value than catching an exception:

    bucket = client.lookup_bucket('doesnt-exist')
    assert not bucket
    # None
    bucket = client.lookup_bucket('my-bucket')
    assert isinstance(bucket, Bucket)
    # <Bucket: my-bucket>
Parameters:bucket_name (str) – The name of the bucket to get.
Return type:google.cloud.storage.bucket.Bucket
Returns:The bucket matching the name provided or None if not found.