Storage Client#
Client for interacting with the Google Cloud Storage API.
-
class
google.cloud.storage.client.
Client
(project=<object object>, credentials=None, _http=None, client_info=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 definesrequest()
with the same interface asrequests.Session.request()
. If not passed, an_http
object is created that is bound to thecredentials
for the current object. This parameter should be considered private, and could change in the future.client_info (
ClientInfo
) – The client info used to send a user-agent string along with API requests. IfNone
, then default info will be used. Generally, you only need to set this if you’re developing your own library or partner tool.
-
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
- 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
- Return type
- 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
- Returns
Instance w/ anonymous credentials and no project.
-
create_bucket
(bucket_or_name, requester_pays=None, project=None)[source]# API call: create a new bucket via a POST request.
See https://cloud.google.com/storage/docs/json_api/v1/buckets/insert
- Parameters
bucket_or_name (Union[
Bucket
, str, ]) – The bucket resource to pass or 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.
- Returns
- google.cloud.storage.bucket.Bucket
The newly created bucket.
- Raises
google.cloud.exceptions.Conflict – If the bucket already exists.
Examples
Create a bucket using a string.
bucket = client.create_bucket("my-bucket") assert isinstance(bucket, Bucket) # <Bucket: my-bucket>
Create a bucket using a resource.
>>> from google.cloud import storage >>> client = storage.Client()
>>> # Set properties on a plain resource object. >>> bucket = storage.Bucket("my-bucket-name") >>> bucket.location = "europe-west6" >>> bucket.storage_class = "COLDLINE"
>>> # Pass that resource object to the client. >>> bucket = client.create_bucket(bucket) # API request.
-
property
current_batch
# Currently-active batch.
- Return type
google.cloud.storage.batch.Batch
orNoneType
(if no batch is active).- Returns
The batch at the top of the batch stack.
-
download_blob_to_file
(blob_or_uri, file_obj, start=None, end=None)[source]# Download the contents of a blob object or blob URI into a file-like object.
- Parameters
Examples
Download a blob using using a blob resource.
>>> from google.cloud import storage >>> client = storage.Client()
>>> bucket = client.get_bucket('my-bucket-name') >>> blob = storage.Blob('path/to/blob', bucket)
>>> with open('file-to-download-to') as file_obj: >>> client.download_blob_to_file(blob, file_obj) # API request.
Download a blob using a URI.
>>> from google.cloud import storage >>> client = storage.Client()
>>> with open('file-to-download-to') as file_obj: >>> client.download_blob_to_file( >>> 'gs://bucket_name/path/to/blob', file_obj)
-
get_bucket
(bucket_or_name)[source]# API call: retrieve a bucket via a GET request.
See https://cloud.google.com/storage/docs/json_api/v1/buckets/get
- Parameters
bucket_or_name (Union[
Bucket
, str, ]) – The bucket resource to pass or name to create.- Returns
- google.cloud.storage.bucket.Bucket
The bucket matching the name provided.
- Raises
google.cloud.exceptions.NotFound – If the bucket is not found.
Examples
Retrieve a bucket using a string.
try: bucket = client.get_bucket("my-bucket") except google.cloud.exceptions.NotFound: print("Sorry, that bucket does not exist!")
Get a bucket using a resource.
>>> from google.cloud import storage >>> client = storage.Client()
>>> # Set properties on a plain resource object. >>> bucket = client.get_bucket("my-bucket-name")
>>> # Time passes. Another program may have modified the bucket ... # in the meantime, so you want to get the latest state. >>> bucket = client.get_bucket(bucket) # API request.
-
get_service_account_email
(project=None)[source]# Get the email address of the project’s GCS service account
-
list_blobs
(bucket_or_name, max_results=None, page_token=None, prefix=None, delimiter=None, versions=None, projection='noAcl', fields=None)[source]# Return an iterator used to find blobs in the bucket.
If
user_project
is set, bills the API request to that project.- Parameters
bucket_or_name (Union[
Bucket
, str, ]) – The bucket resource to pass or name to create.max_results (int) – (Optional) The maximum number of blobs in each page of results from this request. Non-positive values are ignored. Defaults to a sensible value set by the API.
page_token (str) – (Optional) If present, return the next batch of blobs, using the value, which must correspond to the
nextPageToken
value returned in the previous response. Deprecated: use thepages
property of the returned iterator instead of manually passing the token.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 name and language of each blob returned:
'items(name,contentLanguage),nextPageToken'
. See: https://cloud.google.com/storage/docs/json_api/v1/parameters#fields
- Returns
Iterator of all
Blob
in this bucket matching the arguments.
-
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. The maximum number of buckets to return.
page_token (str) – Optional. If present, return the next batch of buckets, using the value, which must correspond to the
nextPageToken
value returned in the previous response. Deprecated: use thepages
property of the returned iterator instead of manually passing the token.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
- Raises
ValueError – if both
project
isNone
and the client’s project is alsoNone
.- 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
- Returns
The bucket matching the name provided or None if not found.