Class Client (3.3.1)

Name

Description

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

google.auth.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

requests.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.

client_info

google.api_core.client_info.ClientInfo

The client info used to send a user-agent string along with API requests. If None , then default info will be used. Generally, you only need to set this if you're developing your own library or partner tool.

client_options

google.api_core.client_options.ClientOptions or dict

(Optional) Client options used to set user options on the client. A non-default universe domain or api endpoint should be set through client_options.

use_auth_w_custom_endpoint

bool

(Optional) Whether authentication is required under custom endpoints. If false, uses AnonymousCredentials and bypasses authentication. Defaults to True. Note this is only used when a custom endpoint is set in conjunction.

extra_headers

dict

(Optional) Custom headers to be sent with the requests attached to the client. For example, you can add custom audit logging headers.

api_key

string

(Optional) An API key. Mutually exclusive with any other credentials. This parameter is an alias for setting client_options.api_key and will supercede any api key set in the client_options parameter.

Type

Description

Batch or NoneType (if no batch is active).

The batch at the top of the batch stack.

Name

Description

raise_exception

bool

(Optional) Defaults to True. If True, instead of adding exceptions to the list of return responses, the final exception will be raised. Note that exceptions are unwrapped after all operations are complete in success or failure, and only the last exception is raised.

Type

Description

Batch

The batch object created.

Name

Description

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.

generation

int

(Optional) If present, selects a specific revision of this bucket.

Type

Description

Bucket

The bucket object created.

Type

Description

Client

Instance w/ anonymous credentials and no project.

Name

Description

bucket_or_name

Union[ Bucket , str, ]

The bucket resource to pass or name to create.

requester_pays

bool

DEPRECATED. Use Bucket().requester_pays instead. (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.

user_project

str

(Optional) The project ID to be billed for API requests made via created bucket.

location

str

(Optional) The location of the bucket. If not passed, the default location, US, will be used. If specifying a dual-region, data_locations should be set in conjunction. See: https://cloud.google.com/storage/docs/locations

data_locations

list of str

(Optional) The list of regional locations of a custom dual-region bucket. Dual-regions require exactly 2 regional locations. See: https://cloud.google.com/storage/docs/locations

predefined_acl

str

(Optional) Name of predefined ACL to apply to bucket. See: https://cloud.google.com/storage/docs/access-control/lists#predefined-acl

predefined_default_object_acl

str

(Optional) Name of predefined ACL to apply to bucket's objects. See: https://cloud.google.com/storage/docs/access-control/lists#predefined-acl

enable_object_retention

bool

(Optional) Whether object retention should be enabled on this bucket. See: https://cloud.google.com/storage/docs/object-lock

timeout

Optional[Union[float, Tuple[float, float]]]

The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). See requests.Session.request documentation for details.

retry

Optional[Union[google.api_core.retry.Retry, google.cloud.storage.retry.ConditionalRetryPolicy ]]

How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and activates it only if certain conditions are met. This class exists to provide safe defaults for RPC calls that are not technically safe to retry normally (due to potential data duplication or other side-effects) but become safe to retry if a condition such as if_metageneration_match is set. See the retry.py source code and docstrings in this package ( google.cloud.storage.retry ) for information on retry types and how to configure them.

Type

Description

google.cloud.exceptions.Conflict

If the bucket already exists.

Name

Description

service_account_email

str

e-mail address of the service account

project_id

str

(Optional) Explicit project ID for the key. Defaults to the client's project.

user_project

str

(Optional) This parameter is currently ignored.

timeout

float or tuple

(Optional) The amount of time, in seconds, to wait for the server response. See: configuring_timeouts

retry

google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy

(Optional) How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and activates it only if certain conditions are met. This class exists to provide safe defaults for RPC calls that are not technically safe to retry normally (due to potential data duplication or other side-effects) but become safe to retry if a condition such as if_metageneration_match is set. See the retry.py source code and docstrings in this package ( google.cloud.storage.retry ) for information on retry types and how to configure them.

Type

Description

Tuple[ HMACKeyMetadata , str]

metadata for the created key, plus the bytes of the key's secret, which is an 40-character base64-encoded string.

Name

Description

blob_or_uri

Union[ Blob , str, ]

The blob resource to pass or URI to download.

file_obj

file

A file handle to which to write the blob's data.

start

int

(Optional) The first byte in a range to be downloaded.

end

int

(Optional) The last byte in a range to be downloaded.

raw_download

bool

(Optional) If true, download the object without any expansion.

if_etag_match

Union[str, Set[str]]

(Optional) See :ref: using-if-etag-match

if_etag_not_match

Union[str, Set[str]]

(Optional) See :ref: using-if-etag-not-match

if_generation_match

long

(Optional) See :ref: using-if-generation-match

if_generation_not_match

long

(Optional) See :ref: using-if-generation-not-match

if_metageneration_match

long

(Optional) See :ref: using-if-metageneration-match

if_metageneration_not_match

long

(Optional) See :ref: using-if-metageneration-not-match

timeout

[Union[float, Tuple[float, float]]]

(Optional) The amount of time, in seconds, to wait for the server response. See: configuring_timeouts

checksum

str

(Optional) The type of checksum to compute to verify the integrity of the object. The response headers must contain a checksum of the requested type. If the headers lack an appropriate checksum (for instance in the case of transcoded or ranged downloads where the remote service does not know the correct checksum, including downloads where chunk_size is set) an INFO-level log will be emitted. Supported values are "md5", "crc32c", "auto" and None. The default is "auto", which will try to detect if the C extension for crc32c is installed and fall back to md5 otherwise.

retry

google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy

(Optional) How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and activates it only if certain conditions are met. This class exists to provide safe defaults for RPC calls that are not technically safe to retry normally (due to potential data duplication or other side-effects) but become safe to retry if a condition such as if_metageneration_match is set. See the retry.py source code and docstrings in this package ( google.cloud.storage.retry ) for information on retry types and how to configure them.

single_shot_download

bool

(Optional) If true, download the object in a single request.

Name

Description

bucket_name

str

Bucket name.

blob_name

str

Object name.

expiration

Union[Integer, datetime.datetime, datetime.timedelta]

Policy expiration time. If a datetime instance is passed without an explicit tzinfo set, it will be assumed to be UTC .

conditions

list

(Optional) List of POST policy conditions, which are used to restrict what is allowed in the request.

fields

dict

(Optional) Additional elements to include into request.

credentials

google.auth.credentials.Signing

(Optional) Credentials object with an associated private key to sign text.

virtual_hosted_style

bool

(Optional) If True, construct the URL relative to the bucket virtual hostname, e.g., '

bucket_bound_hostname

str

(Optional) If passed, construct the URL relative to the bucket-bound hostname. Value can be bare or with a scheme, e.g., 'example.com' or ' http://example.com '. Incompatible with virtual_hosted_style. See: https://cloud.google.com/storage/docs/request-endpoints#cname

scheme

str

(Optional) If bucket_bound_hostname is passed as a bare hostname, use this value as a scheme. https will work only when using a CDN. Defaults to "http" .

service_account_email

str

(Optional) E-mail address of the service account.

access_token

str

(Optional) Access token for a service account.

Type

Description

`ValueError

when mutually exclusive arguments are used.

Type

Description

dict

Signed POST policy.

Name

Description

bucket_or_name

Union[ Bucket , str, ]

The bucket resource to pass or name to create.

timeout

Optional[Union[float, Tuple[float, float]]]

The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). See requests.Session.request documentation for details.

if_metageneration_match

Optional[int]

Make the operation conditional on whether the bucket's current metageneration matches the given value.

if_metageneration_not_match

Optional[int]

Make the operation conditional on whether the bucket's current metageneration does not match the given value.

retry

Optional[Union[google.api_core.retry.Retry, google.cloud.storage.retry.ConditionalRetryPolicy ]]

How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and activates it only if certain conditions are met. This class exists to provide safe defaults for RPC calls that are not technically safe to retry normally (due to potential data duplication or other side-effects) but become safe to retry if a condition such as if_metageneration_match is set. See the retry.py source code and docstrings in this package ( google.cloud.storage.retry ) for information on retry types and how to configure them.

generation

Optional[int]

The generation of the bucket. The generation can be used to specify a specific soft-deleted version of the bucket, in conjunction with the soft_deleted argument below. If soft_deleted is not True, the generation is unused.

soft_deleted

Optional[bool]

If True, looks for a soft-deleted bucket. Will only return the bucket metadata if the bucket exists and is in a soft-deleted state. The bucket generation is required if soft_deleted is set to True. See: https://cloud.google.com/storage/docs/soft-delete

Type

Description

google.cloud.exceptions.NotFound

If the bucket is not found.

Name

Description

access_id

str

Unique ID of an existing key.

project_id

str

(Optional) Project ID of an existing key. Defaults to client's project.

timeout

float or tuple

(Optional) The amount of time, in seconds, to wait for the server response. See: configuring_timeouts

user_project

str

(Optional) This parameter is currently ignored.

Name

Description

project

str

(Optional) Project ID to use for retreiving GCS service account email address. Defaults to the client's project.

timeout

float or tuple

(Optional) The amount of time, in seconds, to wait for the server response. See: configuring_timeouts

retry

google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy

(Optional) How to retry the RPC. See: configuring_retries

Type

Description

str

service account email address

Name

Description

bucket_or_name

Union[ Bucket , str, ]

The bucket resource to pass or name to create.

max_results

int

(Optional) The maximum number of blobs to return.

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 the pages 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.

start_offset

str

(Optional) Filter results to objects whose names are lexicographically equal to or after startOffset . If endOffset is also set, the objects listed will have names between startOffset (inclusive) and endOffset (exclusive).

end_offset

str

(Optional) Filter results to objects whose names are lexicographically before endOffset . If startOffset is also set, the objects listed will have names between startOffset (inclusive) and endOffset (exclusive).

include_trailing_delimiter

boolean

(Optional) If true, objects that end in exactly one instance of delimiter will have their metadata included in items in addition to prefixes .

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

page_size

int

(Optional) Maximum number of blobs to return in each page. Defaults to a value set by the API.

timeout

Optional[Union[float, Tuple[float, float]]]

The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). See requests.Session.request documentation for details.

retry

Optional[Union[google.api_core.retry.Retry, google.cloud.storage.retry.ConditionalRetryPolicy ]]

How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and activates it only if certain conditions are met. This class exists to provide safe defaults for RPC calls that are not technically safe to retry normally (due to potential data duplication or other side-effects) but become safe to retry if a condition such as if_metageneration_match is set. See the retry.py source code and docstrings in this package ( google.cloud.storage.retry ) for information on retry types and how to configure them.

match_glob

str

(Optional) A glob pattern used to filter results (for example, foo*bar). The string value must be UTF-8 encoded. See: https://cloud.google.com/storage/docs/json_api/v1/objects/list#list-object-glob

include_folders_as_prefixes

bool

(Optional) If true, includes Folders and Managed Folders in the set of prefixes returned by the query. Only applicable if delimiter is set to /. See: https://cloud.google.com/storage/docs/managed-folders

soft_deleted

bool

(Optional) If true, only soft-deleted objects will be listed as distinct results in order of increasing generation number. This parameter can only be used successfully if the bucket has a soft delete policy. Note soft_deleted and versions cannot be set to True simultaneously. See: https://cloud.google.com/storage/docs/soft-delete

Name

Description

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 the pages 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.

page_size

int

(Optional) Maximum number of buckets to return in each page. Defaults to a value set by the API.

timeout

float or tuple

(Optional) The amount of time, in seconds, to wait for the server response. See: configuring_timeouts

retry

google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy

(Optional) How to retry the RPC. See: configuring_retries

soft_deleted

bool

(Optional) If true, only soft-deleted buckets will be listed as distinct results in order of increasing generation number. This parameter can only be used successfully if the bucket has a soft delete policy. See: https://cloud.google.com/storage/docs/soft-delete

Type

Description

ValueError

if both project is None and the client's project is also None .

Type

Description

google.api_core.page_iterator.Iterator

Iterator of all Bucket belonging to this project.

Name

Description

max_results

int

(Optional) Max number of keys to return in a given page.

service_account_email

str

(Optional) Limit keys to those created by the given service account.

show_deleted_keys

bool

(Optional) Included deleted keys in the list. Default is to exclude them.

project_id

str

(Optional) Explicit project ID for the key. Defaults to the client's project.

user_project

str

(Optional) This parameter is currently ignored.

timeout

float or tuple

(Optional) The amount of time, in seconds, to wait for the server response. See: configuring_timeouts

retry

google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy

(Optional) How to retry the RPC. See: configuring_retries

Type

Description

Tuple[ HMACKeyMetadata , str]

metadata for the created key, plus the bytes of the key's secret, which is an 40-character base64-encoded string.

Name

Description

bucket_name

str

The name of the bucket to get.

timeout

float or tuple

(Optional) The amount of time, in seconds, to wait for the server response. See: configuring_timeouts

if_metageneration_match

long

(Optional) Make the operation conditional on whether the blob's current metageneration matches the given value.

if_metageneration_not_match

long

(Optional) Make the operation conditional on whether the blob's current metageneration does not match the given value.

retry

google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy

(Optional) How to retry the RPC. See: configuring_retries

Type

Description

Bucket or NoneType

The bucket matching the name provided or None if not found.

Name

Description

bucket_name

str

The name of the bucket to be restored.

generation

int

Selects the specific revision of the bucket.

projection

str

(Optional) Specifies the set of properties to return. If used, must be 'full' or 'noAcl'. Defaults to 'noAcl'. if_metageneration_match (Optional[int]): Make the operation conditional on whether the blob's current metageneration matches the given value. if_metageneration_not_match (Optional[int]): Make the operation conditional on whether the blob's current metageneration does not match the given value.

timeout

float or tuple

(Optional) The amount of time, in seconds, to wait for the server response. See: configuring_timeouts

retry

google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy

(Optional) How to retry the RPC. Users can configure non-default retry behavior. A None value will disable retries. See Configuring Retries .

Type

Description

Bucket

The restored Bucket.