Storage#

Client for interacting with the Google Cloud Storage API.

class google.cloud.storage.client.Client(project=<object object>, credentials=None, _http=None)[source]#

Bases: google.cloud.client.ClientWithProject

Client to bundle configuration needed for API requests.

Parameters:
  • project (str or None) – 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 (Session) – (Optional) HTTP object to make requests. Can be any object that defines request() with the same interface as requests.Session.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, user_project=None)[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.
  • user_project (str) – (Optional) the project ID to be billed for API requests made via the bucket.
Return type:

google.cloud.storage.bucket.Bucket

Returns:

The bucket object created.

classmethod create_anonymous_client()[source]#

Factory: return client with anonymous credentials.

Note

Such a client has only limited access to “public” buckets: listing their contents and downloading their blobs.

Return type:google.cloud.storage.client.Client
Returns:Instance w/ anonymous credentials and no project.
create_bucket(bucket_name, requester_pays=None, project=None)[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.
  • requester_pays (bool) – (Optional) Whether requester pays for API requests for this bucket and its blobs.
  • project (str) – (Optional) the project under which the bucket is to be created. If not passed, uses the project set on the client.
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, project=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’
  • project (str) – (Optional) the project whose buckets are to be listed. If not passed, uses the project set on the client.
Return type:

Iterator

Raises:

ValueError – if both project is None and the client’s project is also None.

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.