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. This parameter should be considered private, and could change in the future.
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.