Storage Client#

Client for interacting with the Google Cloud Storage API.

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

Bases: gcloud.client.JSONClient

Client to bundle configuration needed for API requests.

Parameters:
  • project (string) – 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 (oauth2client.client.OAuth2Credentials or NoneType) – The OAuth2 Credentials to use for the connection owned by this client. If not passed (and if no http object is passed), falls back to the default inferred from the environment.
  • http (httplib2.Http or class that defines request().) – An optional HTTP object to make requests. If not passed, an http object is created that is bound to the credentials for the current object.
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:gcloud.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 (string) – The name of the bucket to be instantiated.
Return type:gcloud.storage.bucket.Bucket
Returns:The bucket object created.
connection#

Get connection or batch on the client.

Return type:gcloud.storage.connection.Connection
Returns:The connection set on the client, or the batch if one is set.
create_bucket(bucket_name)[source]#

Create a new bucket.

For example:

>>> bucket = client.create_bucket('my-bucket')
>>> print bucket
<Bucket: my-bucket>

This implements “storage.buckets.insert”.

If the bucket already exists, will raise gcloud.exceptions.Conflict.

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

Currently-active batch.

Return type:gcloud.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 gcloud.storage.exceptions.NotFound.

For example:

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

This implements “storage.buckets.get”.

Parameters:bucket_name (string) – The name of the bucket to get.
Return type:gcloud.storage.bucket.Bucket
Returns:The bucket matching the name provided.
Raises:gcloud.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 (integer or NoneType) – Optional. Maximum number of buckets to return.
  • page_token (string or NoneType) – Optional. Opaque marker for the next “page” of buckets. If not passed, will return the first page of buckets.
  • prefix (string or NoneType) – Optional. Filter results to buckets whose names begin with this prefix.
  • 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 bucket returned: ‘items/id,nextPageToken’
Return type:

iterable of gcloud.storage.bucket.Bucket objects.

Returns:

All buckets 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')
>>> print bucket
None
>>> bucket = client.lookup_bucket('my-bucket')
>>> print bucket
<Bucket: my-bucket>
Parameters:bucket_name (string) – The name of the bucket to get.
Return type:gcloud.storage.bucket.Bucket
Returns:The bucket matching the name provided or None if not found.

Connection#

Create / interact with gcloud storage connections.

class gcloud.storage.connection.Connection(credentials=None, http=None)[source]#

Bases: gcloud.connection.JSONConnection

A connection to Google Cloud Storage via the JSON REST API.

Parameters:
API_BASE_URL = 'https://www.googleapis.com'#

The base of the API call URL.

API_URL_TEMPLATE = '{api_base_url}/storage/{api_version}{path}'#

A template for the URL of a particular API call.

API_VERSION = 'v1'#

The version of the API, used in building the API call’s URL.

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.