google-cloud-storage API Reference
Full documentation for google-cloud-storage (3.13.0)
google-cloud-storage.Batch
Python Library Documentation: class Batch in module google.cloud.storage.batch
class Batch(google.cloud.storage._http.Connection)
| Batch(client, raise_exception=True)
|
| Proxy an underlying connection, batching up change operations.
|
| .. warning::
|
| Cloud Storage does not support batch operations for uploading or downloading.
| Additionally, the current batch design does not support library methods whose
| return values depend on the response payload.
|
| :type client: :class:`google.cloud.storage.client.Client`
| :param client: The client to use for making connections.
|
| :type raise_exception: bool
| :param raise_exception:
| (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.
|
| Method resolution order:
| Batch
| google.cloud.storage._http.Connection
| google.cloud._http.JSONConnection
| google.cloud._http.Connection
| builtins.object
|
| Methods defined here:
|
| __enter__(self)
|
| __exit__(self, exc_type, exc_val, exc_tb)
|
| __init__(self, client, raise_exception=True)
| Initialize self. See help(type(self)) for accurate signature.
|
| current(self)
| Return the topmost batch, or None.
|
| finish(self, raise_exception=True)
| Submit a single `multipart/mixed` request with deferred requests.
|
| :type raise_exception: bool
| :param raise_exception:
| (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.
|
| :rtype: list of tuples
| :returns: one ``(headers, payload)`` tuple per deferred request.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from google.cloud.storage._http.Connection:
|
| api_request(self, *args, **kwargs)
| Make a request over the HTTP transport to the API.
|
| You shouldn't need to use this method, but if you plan to
| interact with the API using these primitives, this is the
| correct one to use.
|
| :type method: str
| :param method: The HTTP method name (ie, ``GET``, ``POST``, etc).
| Required.
|
| :type path: str
| :param path: The path to the resource (ie, ``'/b/bucket-name'``).
| Required.
|
| :type query_params: dict or list
| :param query_params: A dictionary of keys and values (or list of
| key-value pairs) to insert into the query
| string of the URL.
|
| :type data: str
| :param data: The data to send as the body of the request. Default is
| the empty string.
|
| :type content_type: str
| :param content_type: The proper MIME type of the data provided. Default
| is None.
|
| :type headers: dict
| :param headers: extra HTTP headers to be sent with the request.
|
| :type api_base_url: str
| :param api_base_url: The base URL for the API endpoint.
| Typically you won't have to provide this.
| Default is the standard API base URL.
|
| :type api_version: str
| :param api_version: The version of the API to call. Typically
| you shouldn't provide this and instead use
| the default for the library. Default is the
| latest API version supported by
| google-cloud-python.
|
| :type expect_json: bool
| :param expect_json: If True, this method will try to parse the
| response as JSON and raise an exception if
| that cannot be done. Default is True.
|
| :type _target_object: :class:`object`
| :param _target_object:
| (Optional) Protected argument to be used by library callers. This
| can allow custom behavior, for example, to defer an HTTP request
| and complete initialization of the object at a later time.
|
| :type timeout: float or tuple
| :param timeout: (optional) The amount of time, in seconds, to wait
| for the server response.
|
| Can also be passed as a tuple (connect_timeout, read_timeout).
| See :meth:`requests.Session.request` documentation for details.
|
| :type extra_api_info: string
| :param extra_api_info: (optional) Extra api info to be appended to
| the X-Goog-API-Client header
|
| :raises ~google.cloud.exceptions.GoogleCloudError: if the response code
| is not 200 OK.
| :raises ValueError: if the response content type is not JSON.
| :rtype: dict or str
| :returns: The API response payload, either as a raw string or
| a dictionary if the response is valid JSON.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from google.cloud.storage._http.Connection:
|
| API_URL_TEMPLATE = '{api_base_url}/storage/{api_version}{path}'
|
| API_VERSION = 'v1'
|
| DEFAULT_API_ENDPOINT = 'https://storage.googleapis.com'
|
| DEFAULT_API_MTLS_ENDPOINT = 'https://storage.mtls.googleapis.com'
|
| ----------------------------------------------------------------------
| Methods inherited from google.cloud._http.JSONConnection:
|
| build_api_url(self, path, query_params=None, api_base_url=None, api_version=None)
| Construct an API url given a few components, some optional.
|
| Typically, you shouldn't need to use this method.
|
| :type path: str
| :param path: The path to the resource (ie, ``'/b/bucket-name'``).
|
| :type query_params: dict or list
| :param query_params: A dictionary of keys and values (or list of
| key-value pairs) to insert into the query
| string of the URL.
|
| :type api_base_url: str
| :param api_base_url: The base URL for the API endpoint.
| Typically you won't have to provide this.
|
| :type api_version: str
| :param api_version: The version of the API to call.
| Typically you shouldn't provide this and instead
| use the default for the library.
|
| :rtype: str
| :returns: The URL assembled from the pieces provided.
|
| get_api_base_url_for_mtls(self, api_base_url=None)
| Return the api base url for mutual TLS.
|
| Typically, you shouldn't need to use this method.
|
| The logic is as follows:
|
| If `api_base_url` is provided, just return this value; otherwise, the
| return value depends `GOOGLE_API_USE_MTLS_ENDPOINT` environment variable
| value.
|
| If the environment variable value is "always", return `API_BASE_MTLS_URL`.
| If the environment variable value is "never", return `API_BASE_URL`.
| Otherwise, if `ALLOW_AUTO_SWITCH_TO_MTLS_URL` is True and the underlying
| http is mTLS, then return `API_BASE_MTLS_URL`; otherwise return `API_BASE_URL`.
|
| :type api_base_url: str
| :param api_base_url: User provided api base url. It takes precedence over
| `API_BASE_URL` and `API_BASE_MTLS_URL`.
|
| :rtype: str
| :returns: The api base url used for mTLS.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from google.cloud._http.JSONConnection:
|
| ALLOW_AUTO_SWITCH_TO_MTLS_URL = False
|
| API_BASE_MTLS_URL = None
|
| API_BASE_URL = None
|
| ----------------------------------------------------------------------
| Readonly properties inherited from google.cloud._http.Connection:
|
| credentials
| Getter for current credentials.
|
| :rtype: :class:`google.auth.credentials.Credentials` or
| :class:`NoneType`
| :returns: The credentials object associated with this connection.
|
| http
| A getter for the HTTP transport used in talking to the API.
|
| Returns:
| google.auth.transport.requests.AuthorizedSession:
| A :class:`requests.Session` instance.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from google.cloud._http.Connection:
|
| USER_AGENT
| Deprecated: get / set user agent sent by connection.
|
| :rtype: str
| :returns: user agent
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| extra_headers
| Get / set extra headers sent by connection.
|
| :rtype: dict
| :returns: header keys / values
|
| user_agent
| Get / set user agent sent by connection.
|
| :rtype: str
| :returns: user agent
google-cloud-storage.Blob
Python Library Documentation: class Blob in module google.cloud.storage.blob
class Blob(google.cloud.storage._helpers._PropertyMixin)
| Blob(name, bucket, chunk_size=None, encryption_key=None, kms_key_name=None, generation=None)
|
| A wrapper around Cloud Storage's concept of an ``Object``.
|
| :type name: str
| :param name: The name of the blob. This corresponds to the unique path of
| the object in the bucket. If bytes, will be converted to a
| unicode object. Blob / object names can contain any sequence
| of valid unicode characters, of length 1-1024 bytes when
| UTF-8 encoded.
|
| :type bucket: :class:`google.cloud.storage.bucket.Bucket`
| :param bucket: The bucket to which this blob belongs.
|
| :type chunk_size: int
| :param chunk_size:
| (Optional) The size of a chunk of data whenever iterating (in bytes).
| This must be a multiple of 256 KB per the API specification. If not
| specified, the chunk_size of the blob itself is used. If that is not
| specified, a default value of 40 MB is used.
|
| :type encryption_key: bytes
| :param encryption_key:
| (Optional) 32 byte encryption key for customer-supplied encryption.
| See https://cloud.google.com/storage/docs/encryption#customer-supplied.
|
| :type kms_key_name: str
| :param kms_key_name:
| (Optional) Resource name of Cloud KMS key used to encrypt the blob's
| contents.
|
| :type generation: long
| :param generation:
| (Optional) If present, selects a specific revision of this object.
|
| Method resolution order:
| Blob
| google.cloud.storage._helpers._PropertyMixin
| builtins.object
|
| Methods defined here:
|
| __init__(self, name, bucket, chunk_size=None, encryption_key=None, kms_key_name=None, generation=None)
| property :attr:`name`
| Get the blob's name.
|
| __repr__(self)
| Return repr(self).
|
| compose(self, sources, client=None, timeout=60, if_generation_match=None, if_metageneration_match=None, if_source_generation_match=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2CF29F40>, destination_contexts=None, delete_source_objects=None)
| Concatenate source blobs into this one.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/objects/compose)
| and a [code sample](https://cloud.google.com/storage/docs/samples/storage-compose-file#storage_compose_file-python).
|
| :type sources: list of :class:`Blob`
| :param sources: Blobs whose contents will be composed into this blob.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) Makes the operation conditional on whether the
| destination object's current generation matches the given value.
| Setting to 0 makes the operation succeed only if there are no live
| versions of the object.
| Note: In a previous version, this argument worked identically to the
| ``if_source_generation_match`` argument. For
| backwards-compatibility reasons, if a list is passed in,
| this argument will behave like ``if_source_generation_match``
| and also issue a DeprecationWarning.
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) Makes the operation conditional on whether the
| destination object's current metageneration matches the given
| value.
|
| If a list of long is passed in, no match operation will be
| performed. (Deprecated: type(list of long) is supported for
| backwards-compatability reasons only.)
|
| :type if_source_generation_match: list of long
| :param if_source_generation_match:
| (Optional) Makes the operation conditional on whether the current
| generation of each source blob matches the corresponding generation.
| The list must match ``sources`` item-to-item.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC.
| The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
| policy which will only enable retries if ``if_generation_match`` or ``generation``
| is set, in order to ensure requests are idempotent before retrying them.
| Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
| to enable retries regardless of generation precondition setting.
| See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| :type destination_contexts: :class:`~google.cloud.storage.blob.ObjectContexts`
| :param destination_contexts:
| (Optional) New contexts to set for the destination object.
| See: https://docs.cloud.google.com/storage/docs/use-object-contexts#manage_object_contexts_during_object_operations
|
| :type delete_source_objects: bool
| :param delete_source_objects:
| (Optional) If True, the source objects will be deleted after a
| successful composition.
|
| create_resumable_upload_session(self, content_type=None, size=None, origin=None, client=None, timeout=60, checksum='auto', predefined_acl=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Create a resumable upload session.
|
| Resumable upload sessions allow you to start an upload session from
| one client and complete the session in another. This method is called
| by the initiator to set the metadata and limits. The initiator then
| passes the session URL to the client that will upload the binary data.
| The client performs a PUT request on the session URL to complete the
| upload. This process allows untrusted clients to upload to an
| access-controlled bucket.
|
| For more details, see the
| documentation on [`signed URLs`](https://cloud.google.com/storage/docs/access-control/signed-urls#signing-resumable).
|
| The content type of the upload will be determined in order
| of precedence:
|
| - The value passed in to this method (if not :data:`None`)
| - The value stored on the current blob
| - The default value ('application/octet-stream')
|
| .. note::
| The effect of uploading to an existing blob depends on the
| "versioning" and "lifecycle" policies defined on the blob's
| bucket. In the absence of those policies, upload will
| overwrite any existing contents.
|
| See the [`object versioning`](https://cloud.google.com/storage/docs/object-versioning)
| and [`lifecycle`](https://cloud.google.com/storage/docs/lifecycle)
| API documents for details.
|
| If :attr:`encryption_key` is set, the blob will be encrypted with
| a [`customer-supplied`](https://cloud.google.com/storage/docs/encryption#customer-supplied)
| encryption key.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type size: int
| :param size:
| (Optional) The maximum number of bytes that can be uploaded using
| this session. If the size is not known when creating the session,
| this should be left blank.
|
| :type content_type: str
| :param content_type: (Optional) Type of content being uploaded.
|
| :type origin: str
| :param origin:
| (Optional) If set, the upload can only be completed by a user-agent
| that uploads from the given origin. This can be useful when passing
| the session to a web client.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type checksum: str
| :param checksum:
| (Optional) The type of checksum to compute to verify
| the integrity of the object. After the upload is complete, the
| server-computed checksum of the resulting object will be checked
| and google.cloud.storage.exceptions.DataCorruption will be raised on
| a mismatch. On a validation failure, the client will attempt to
| delete the uploaded object automatically. 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.
|
| :type predefined_acl: str
| :param predefined_acl: (Optional) Predefined access control list
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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_generation_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.
|
| :rtype: str
| :returns: The resumable upload session URL. The upload can be
| completed by making an HTTP PUT request with the
| file's contents.
|
| :raises: :class:`google.cloud.exceptions.GoogleCloudError`
| if the session creation response returns an error status.
|
| delete(self, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Deletes a blob from Cloud Storage.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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_generation_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.
|
| :raises: :class:`google.cloud.exceptions.NotFound`
| (propagated from
| :meth:`google.cloud.storage.bucket.Bucket.delete_blob`).
|
| download_as_bytes(self, client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='auto', retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, single_shot_download=False)
| Download the contents of this blob as a bytes object.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type start: int
| :param start: (Optional) The first byte in a range to be downloaded.
|
| :type end: int
| :param end: (Optional) The last byte in a range to be downloaded.
|
| :type raw_download: bool
| :param raw_download:
| (Optional) If true, download the object without any expansion.
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match:
| (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]]
| :param if_etag_not_match:
| (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type checksum: str
| :param checksum:
| (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.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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 single_shot_download: bool
| :param single_shot_download:
| (Optional) If true, download the object in a single request.
| Caution: Enabling this will increase the memory overload for your application.
| Please enable this as per your use case.
|
| :rtype: bytes
| :returns: The data stored in this blob.
|
| :raises: :class:`google.cloud.exceptions.NotFound`
|
| download_as_string(self, client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, single_shot_download=False)
| (Deprecated) Download the contents of this blob as a bytes object.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| .. note::
| Deprecated alias for :meth:`download_as_bytes`.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type start: int
| :param start: (Optional) The first byte in a range to be downloaded.
|
| :type end: int
| :param end: (Optional) The last byte in a range to be downloaded.
|
| :type raw_download: bool
| :param raw_download:
| (Optional) If true, download the object without any expansion.
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match:
| (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]]
| :param if_etag_not_match:
| (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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 single_shot_download: bool
| :param single_shot_download:
| (Optional) If true, download the object in a single request.
| Caution: Enabling this will increase the memory overload for your application.
| Please enable this as per your use case.
|
| :rtype: bytes
| :returns: The data stored in this blob.
|
| :raises: :class:`google.cloud.exceptions.NotFound`
|
| download_as_text(self, client=None, start=None, end=None, raw_download=False, encoding=None, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, single_shot_download=False)
| Download the contents of this blob as text (*not* bytes).
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type start: int
| :param start: (Optional) The first byte in a range to be downloaded.
|
| :type end: int
| :param end: (Optional) The last byte in a range to be downloaded.
|
| :type raw_download: bool
| :param raw_download:
| (Optional) If true, download the object without any expansion.
|
| :type encoding: str
| :param encoding: (Optional) encoding to be used to decode the
| downloaded bytes. Defaults to the ``charset`` param of
| attr:`content_type`, or else to "utf-8".
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match:
| (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]]
| :param if_etag_not_match:
| (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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 single_shot_download: bool
| :param single_shot_download:
| (Optional) If true, download the object in a single request.
| Caution: Enabling this will increase the memory overload for your application.
| Please enable this as per your use case.
|
| :rtype: text
| :returns: The data stored in this blob, decoded to text.
|
| download_to_file(self, file_obj, client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='auto', retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, single_shot_download=False)
| Download the contents of this blob into a file-like object.
|
| .. note::
|
| If the server-set property, :attr:`media_link`, is not yet
| initialized, makes an additional API request to load it.
|
| If the :attr:`chunk_size` of a current blob is `None`, will download data
| in single download request otherwise it will download the :attr:`chunk_size`
| of data in each request.
|
| For more fine-grained control over the download process, check out
| [`google-resumable-media`](https://googleapis.dev/python/google-resumable-media/latest/index.html).
| For example, this library allows downloading **parts** of a blob rather than the whole thing.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type file_obj: file
| :param file_obj: A file handle to which to write the blob's data.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type start: int
| :param start: (Optional) The first byte in a range to be downloaded.
|
| :type end: int
| :param end: (Optional) The last byte in a range to be downloaded.
|
| :type raw_download: bool
| :param raw_download:
| (Optional) If true, download the object without any expansion.
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match:
| (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]]
| :param if_etag_not_match:
| (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type checksum: str
| :param checksum:
| (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.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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 single_shot_download: bool
| :param single_shot_download:
| (Optional) If true, download the object in a single request.
| Caution: Enabling this will increase the memory overload for your application.
| Please enable this as per your use case.
|
| :raises: :class:`google.cloud.exceptions.NotFound`
|
| download_to_filename(self, filename, client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='auto', retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, single_shot_download=False)
| Download the contents of this blob into a named file.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| See a [code sample](https://cloud.google.com/storage/docs/samples/storage-download-encrypted-file#storage_download_encrypted_file-python)
| to download a file with a [`customer-supplied encryption key`](https://cloud.google.com/storage/docs/encryption#customer-supplied).
|
| :type filename: str
| :param filename: A filename to be passed to ``open``.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type start: int
| :param start: (Optional) The first byte in a range to be downloaded.
|
| :type end: int
| :param end: (Optional) The last byte in a range to be downloaded.
|
| :type raw_download: bool
| :param raw_download:
| (Optional) If true, download the object without any expansion.
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match:
| (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]]
| :param if_etag_not_match:
| (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type checksum: str
| :param checksum:
| (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.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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 single_shot_download: bool
| :param single_shot_download:
| (Optional) If true, download the object in a single request.
| Caution: Enabling this will increase the memory overload for your application.
| Please enable this as per your use case.
|
| :raises: :class:`google.cloud.exceptions.NotFound`
|
| exists(self, client=None, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, soft_deleted=None)
| Determines whether or not this blob exists.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match:
| (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]]
| :param if_etag_not_match:
| (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type soft_deleted: bool
| :param soft_deleted:
| (Optional) If True, looks for a soft-deleted object. Will only return True
| if the object exists and is in a soft-deleted state.
| :attr:`generation` is required to be set on the blob if ``soft_deleted`` is set to True.
| See: https://cloud.google.com/storage/docs/soft-delete
|
| :rtype: bool
| :returns: True if the blob exists in Cloud Storage.
|
| generate_signed_url(self, expiration=None, api_access_endpoint=None, method='GET', content_md5=None, content_type=None, response_disposition=None, response_type=None, generation=None, headers=None, query_parameters=None, client=None, credentials=None, version=None, service_account_email=None, access_token=None, virtual_hosted_style=False, bucket_bound_hostname=None, scheme='http')
| Generates a signed URL for this blob.
|
| .. note::
|
| If you are on Google Compute Engine, you can't generate a signed
| URL using GCE service account.
| If you'd like to be able to generate a signed URL from GCE,
| you can use a standard service account from a JSON file rather
| than a GCE service account.
|
| If you have a blob that you want to allow access to for a set
| amount of time, you can use this method to generate a URL that
| is only valid within a certain time period.
|
| See a [code sample](https://cloud.google.com/storage/docs/samples/storage-generate-signed-url-v4#storage_generate_signed_url_v4-python).
|
| This is particularly useful if you don't want publicly
| accessible blobs, but don't want to require users to explicitly
| log in.
|
| If ``bucket_bound_hostname`` is set as an argument of :attr:`api_access_endpoint`,
| ``https`` works only if using a ``CDN``.
|
| :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
| :param expiration:
| Point in time when the signed URL should expire. If a ``datetime``
| instance is passed without an explicit ``tzinfo`` set, it will be
| assumed to be ``UTC``.
|
| :type api_access_endpoint: str
| :param api_access_endpoint: (Optional) URI base, for instance
| "https://storage.googleapis.com". If not specified, the client's
| api_endpoint will be used. Incompatible with bucket_bound_hostname.
|
| :type method: str
| :param method: The HTTP verb that will be used when requesting the URL.
|
| :type content_md5: str
| :param content_md5:
| (Optional) The MD5 hash of the object referenced by ``resource``.
|
| :type content_type: str
| :param content_type:
| (Optional) The content type of the object referenced by
| ``resource``.
|
| :type response_disposition: str
| :param response_disposition:
| (Optional) Content disposition of responses to requests for the
| signed URL. For example, to enable the signed URL to initiate a
| file of ``blog.png``, use the value ``'attachment;
| filename=blob.png'``.
|
| :type response_type: str
| :param response_type:
| (Optional) Content type of responses to requests for the signed
| URL. Ignored if content_type is set on object/blob metadata.
|
| :type generation: str
| :param generation:
| (Optional) A value that indicates which generation of the resource
| to fetch.
|
| :type headers: dict
| :param headers:
| (Optional) Additional HTTP headers to be included as part of the
| signed URLs. See:
| https://cloud.google.com/storage/docs/xml-api/reference-headers
| Requests using the signed URL *must* pass the specified header
| (name and value) with each request for the URL.
|
| :type query_parameters: dict
| :param query_parameters:
| (Optional) Additional query parameters to be included as part of the
| signed URLs. See:
| https://cloud.google.com/storage/docs/xml-api/reference-headers#query
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type credentials: :class:`google.auth.credentials.Credentials`
| :param credentials:
| (Optional) The authorization credentials to attach to requests.
| These credentials identify this application to the service. If
| none are specified, the client will attempt to ascertain the
| credentials from the environment.
|
| :type version: str
| :param version:
| (Optional) The version of signed credential to create. Must be one
| of 'v2' | 'v4'.
|
| :type service_account_email: str
| :param service_account_email:
| (Optional) E-mail address of the service account.
|
| :type access_token: str
| :param access_token: (Optional) Access token for a service account.
|
| :type virtual_hosted_style: bool
| :param virtual_hosted_style:
| (Optional) If true, then construct the URL relative the bucket's
| virtual hostname, e.g., '<bucket-name>.storage.googleapis.com'.
| Incompatible with bucket_bound_hostname.
|
| :type bucket_bound_hostname: str
| :param bucket_bound_hostname:
| (Optional) If passed, then construct the URL relative to the bucket-bound hostname.
| Value can be a bare or with scheme, e.g., 'example.com' or 'http://example.com'.
| Incompatible with api_access_endpoint and virtual_hosted_style.
| See: https://cloud.google.com/storage/docs/request-endpoints#cname
|
| :type scheme: str
| :param scheme:
| (Optional) If ``bucket_bound_hostname`` is passed as a bare
| hostname, use this value as the scheme. ``https`` will work only
| when using a CDN. Defaults to ``"http"``.
|
| :raises: :exc:`ValueError` when version is invalid or mutually exclusive arguments are used.
| :raises: :exc:`TypeError` when expiration is not a valid type.
| :raises: :exc:`AttributeError` if credentials is not an instance
| of :class:`google.auth.credentials.Signing`.
|
| :rtype: str
| :returns: A signed URL you can use to access the resource
| until expiration.
|
| get_iam_policy(self, client=None, requested_policy_version=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Retrieve the IAM policy for the object.
|
| .. note::
|
| Blob- / object-level IAM support does not yet exist and methods
| currently call an internal ACL backend not providing any utility
| beyond the blob's :attr:`acl` at this time. The API may be enhanced
| in the future and is currently undocumented. Use :attr:`acl` for
| managing object access control.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the current object's bucket.
|
| :type requested_policy_version: int or ``NoneType``
| :param requested_policy_version:
| (Optional) The version of IAM policies to request. If a policy
| with a condition is requested without setting this, the server will
| return an error. This must be set to a value of 3 to retrieve IAM
| policies containing conditions. This is to prevent client code that
| isn't aware of IAM conditions from interpreting and modifying
| policies incorrectly. The service might return a policy with
| version lower than the one that was requested, based on the feature
| syntax in the policy fetched.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: :class:`google.api_core.iam.Policy`
| :returns: the policy instance, based on the resource returned from
| the ``getIamPolicy`` API request.
|
| make_private(self, client=None, timeout=60, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Update blob's ACL, revoking read access for anonymous users.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the blob's bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| make_public(self, client=None, timeout=60, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Update blob's ACL, granting read access to anonymous users.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the blob's bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| open(self, mode='r', chunk_size=None, ignore_flush=None, encoding=None, errors=None, newline=None, **kwargs)
| Create a file handler for file-like I/O to or from this blob.
|
| This method can be used as a context manager, just like Python's
| built-in 'open()' function.
|
| While reading, as with other read methods, if blob.generation is not set
| the most recent blob generation will be used. Because the file-like IO
| reader downloads progressively in chunks, this could result in data from
| multiple versions being mixed together. If this is a concern, use
| either bucket.get_blob(), or blob.reload(), which will download the
| latest generation number and set it; or, if the generation is known, set
| it manually, for instance with bucket.blob(generation=123456).
|
| Checksumming (hashing) to verify data integrity is disabled for reads
| using this feature because reads are implemented using request ranges,
| which do not provide checksums to validate. See
| https://cloud.google.com/storage/docs/hashes-etags for details.
|
| See a [code sample](https://github.com/googleapis/python-storage/blob/main/samples/snippets/storage_fileio_write_read.py).
|
| Keyword arguments to pass to the underlying API calls.
| For both uploads and downloads, the following arguments are
| supported:
|
| - ``if_generation_match``
| - ``if_generation_not_match``
| - ``if_metageneration_match``
| - ``if_metageneration_not_match``
| - ``timeout``
| - ``retry``
|
| For downloads only, the following additional arguments are supported:
|
| - ``raw_download``
| - ``single_shot_download``
|
| For uploads only, the following additional arguments are supported:
|
| - ``content_type``
| - ``predefined_acl``
| - ``checksum``
|
| :type mode: str
| :param mode:
| (Optional) A mode string, as per standard Python `open()` semantics.The first
| character must be 'r', to open the blob for reading, or 'w' to open
| it for writing. The second character, if present, must be 't' for
| (unicode) text mode, or 'b' for bytes mode. If the second character
| is omitted, text mode is the default.
|
| :type chunk_size: long
| :param chunk_size:
| (Optional) For reads, the minimum number of bytes to read at a time.
| If fewer bytes than the chunk_size are requested, the remainder is
| buffered. For writes, the maximum number of bytes to buffer before
| sending data to the server, and the size of each request when data
| is sent. Writes are implemented as a "resumable upload", so
| chunk_size for writes must be exactly a multiple of 256KiB as with
| other resumable uploads. The default is 40 MiB.
|
| :type ignore_flush: bool
| :param ignore_flush:
| (Optional) For non text-mode writes, makes flush() do nothing
| instead of raising an error. flush() without closing is not
| supported by the remote service and therefore calling it normally
| results in io.UnsupportedOperation. However, that behavior is
| incompatible with some consumers and wrappers of file objects in
| Python, such as zipfile.ZipFile or io.TextIOWrapper. Setting
| ignore_flush will cause flush() to successfully do nothing, for
| compatibility with those contexts. The correct way to actually flush
| data to the remote server is to close() (using a context manager,
| such as in the example, will cause this to happen automatically).
|
| :type encoding: str
| :param encoding:
| (Optional) For text mode only, the name of the encoding that the stream will
| be decoded or encoded with. If omitted, it defaults to
| locale.getpreferredencoding(False).
|
| :type errors: str
| :param errors:
| (Optional) For text mode only, an optional string that specifies how encoding
| and decoding errors are to be handled. Pass 'strict' to raise a
| ValueError exception if there is an encoding error (the default of
| None has the same effect), or pass 'ignore' to ignore errors. (Note
| that ignoring encoding errors can lead to data loss.) Other more
| rarely-used options are also available; see the Python 'io' module
| documentation for 'io.TextIOWrapper' for a complete list.
|
| :type newline: str
| :param newline:
| (Optional) For text mode only, controls how line endings are handled. It can
| be None, '', '\n', '\r', and '\r\n'. If None, reads use "universal
| newline mode" and writes use the system default. See the Python
| 'io' module documentation for 'io.TextIOWrapper' for details.
|
| :returns: A 'BlobReader' or 'BlobWriter' from
| 'google.cloud.storage.fileio', or an 'io.TextIOWrapper' around one
| of those classes, depending on the 'mode' argument.
|
| rewrite(self, source, token=None, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, if_source_generation_match=None, if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2CF29F40>, destination_contexts=None)
| Rewrite source blob into this one.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| .. note::
|
| ``rewrite`` is not supported in a ``Batch`` context.
|
| :type source: :class:`Blob`
| :param source: blob whose contents will be rewritten into this blob.
|
| :type token: str
| :param token:
| (Optional) Token returned from an earlier, not-completed call to
| rewrite the same source blob. If passed, result will include
| updated status, total bytes written.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_source_generation_match: long
| :param if_source_generation_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation matches the given value.
|
| :type if_source_generation_not_match: long
| :param if_source_generation_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation does not match the given value.
|
| :type if_source_metageneration_match: long
| :param if_source_metageneration_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration matches the given value.
|
| :type if_source_metageneration_not_match: long
| :param if_source_metageneration_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration does not match the given value.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC.
| The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
| policy which will only enable retries if ``if_generation_match`` or ``generation``
| is set, in order to ensure requests are idempotent before retrying them.
| Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
| to enable retries regardless of generation precondition setting.
| See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| :type destination_contexts: :class:`~google.cloud.storage.blob.ObjectContexts` or dict
| :param destination_contexts:
| (Optional) New contexts to set for the destination object.
| See: https://docs.cloud.google.com/storage/docs/use-object-contexts#manage_object_contexts_during_object_operations
|
| :rtype: tuple
| :returns: ``(token, bytes_rewritten, total_bytes)``, where ``token``
| is a rewrite token (``None`` if the rewrite is complete),
| ``bytes_rewritten`` is the number of bytes rewritten so far,
| and ``total_bytes`` is the total number of bytes to be
| rewritten.
|
| set_iam_policy(self, policy, client=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920980>)
| Update the IAM policy for the bucket.
|
| .. note::
|
| Blob- / object-level IAM support does not yet exist and methods
| currently call an internal ACL backend not providing any utility
| beyond the blob's :attr:`acl` at this time. The API may be enhanced
| in the future and is currently undocumented. Use :attr:`acl` for
| managing object access control.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type policy: :class:`google.api_core.iam.Policy`
| :param policy: policy instance used to update bucket's IAM policy.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the current bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: :class:`google.api_core.iam.Policy`
| :returns: the policy instance, based on the resource returned from
| the ``setIamPolicy`` API request.
|
| test_iam_permissions(self, permissions, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| API call: test permissions
|
| .. note::
|
| Blob- / object-level IAM support does not yet exist and methods
| currently call an internal ACL backend not providing any utility
| beyond the blob's :attr:`acl` at this time. The API may be enhanced
| in the future and is currently undocumented. Use :attr:`acl` for
| managing object access control.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type permissions: list of string
| :param permissions: the permissions to check
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the current bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: list of string
| :returns: the permissions returned by the ``testIamPermissions`` API
| request.
|
| update_storage_class(self, new_class, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, if_source_generation_match=None, if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2CF29F40>)
| Update blob's storage class via a rewrite-in-place. This helper will
| wait for the rewrite to complete before returning, so it may take some
| time for large files.
|
| See
| https://cloud.google.com/storage/docs/per-object-storage-class
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type new_class: str
| :param new_class:
| new storage class for the object. One of:
| :attr:`~google.cloud.storage.constants.NEARLINE_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.COLDLINE_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.ARCHIVE_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.STANDARD_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.MULTI_REGIONAL_LEGACY_STORAGE_CLASS`,
| or
| :attr:`~google.cloud.storage.constants.REGIONAL_LEGACY_STORAGE_CLASS`.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_source_generation_match: long
| :param if_source_generation_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation matches the given value.
|
| :type if_source_generation_not_match: long
| :param if_source_generation_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation does not match the given value.
|
| :type if_source_metageneration_match: long
| :param if_source_metageneration_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration matches the given value.
|
| :type if_source_metageneration_not_match: long
| :param if_source_metageneration_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration does not match the given value.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC.
| The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
| policy which will only enable retries if ``if_generation_match`` or ``generation``
| is set, in order to ensure requests are idempotent before retrying them.
| Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
| to enable retries regardless of generation precondition setting.
| See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| upload_from_file(self, file_obj, rewind=False, size=None, content_type=None, client=None, predefined_acl=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='auto', retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, crc32c_checksum_value=None)
| Upload the contents of this blob from a file-like object.
|
| The content type of the upload will be determined in order
| of precedence:
|
| - The value passed in to this method (if not :data:`None`)
| - The value stored on the current blob
| - The default value ('application/octet-stream')
|
| .. note::
| The effect of uploading to an existing blob depends on the
| "versioning" and "lifecycle" policies defined on the blob's
| bucket. In the absence of those policies, upload will
| overwrite any existing contents.
|
| See the [`object versioning`](https://cloud.google.com/storage/docs/object-versioning)
| and [`lifecycle`](https://cloud.google.com/storage/docs/lifecycle)
| API documents for details.
|
| If the size of the data to be uploaded exceeds 8 MB a resumable media
| request will be used, otherwise the content and the metadata will be
| uploaded in a single multipart upload request.
|
| For more fine-grained over the upload process, check out
| [`google-resumable-media`](https://googleapis.dev/python/google-resumable-media/latest/index.html).
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type file_obj: file
| :param file_obj: A file handle opened in binary mode for reading.
|
| :type rewind: bool
| :param rewind:
| If True, seek to the beginning of the file handle before writing
| the file to Cloud Storage.
|
| :type size: int
| :param size:
| The number of bytes to be uploaded (which will be read from
| ``file_obj``). If not provided, the upload will be concluded once
| ``file_obj`` is exhausted.
|
| :type content_type: str
| :param content_type: (Optional) Type of content being uploaded.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type predefined_acl: str
| :param predefined_acl: (Optional) Predefined access control list
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type checksum: str
| :param checksum:
| (Optional) The type of checksum to compute to verify
| the integrity of the object. If the upload is completed in a single
| request, the checksum will be entirely precomputed and the remote
| server will handle verification and error handling. If the upload
| is too large and must be transmitted in multiple requests, the
| checksum will be incrementally computed and the client will handle
| verification and error handling, raising
| google.cloud.storage.exceptions.DataCorruption on a mismatch and
| attempting to delete the corrupted file. 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.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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_generation_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 crc32c_checksum_value: str
| :param crc32c_checksum_value: (Optional) This should be the checksum of
| the entire contents of `file_obj`. Applicable while uploading object
| greater than `_MAX_MULTIPART_SIZE` bytes.
|
| It can be obtained by running
|
| `gcloud storage hash /path/to/your/file`
|
| or
|
| .. code-block:: python
|
| import google_crc32c
| import base64
|
| data = b"Hello, world!"
| crc32c_int = google_crc32c.value(data)
| crc32c_hex = f"{crc32c_int:08x}"
| crc32c_bytes = crc32c_int.to_bytes(4, "big")
| base64_encoded = base64.b64encode(crc32c_bytes)
| crc32c_base64 = base64_encoded.decode("utf-8")
|
| print(crc32c_base64)
|
| Above code block prints 8 char string of base64 encoded big-endian
| bytes of 32 bit CRC32c integer.
|
| More details on CRC32c can be found in Appendix B:
| https://datatracker.ietf.org/doc/html/rfc4960#appendix-B and
| base64: https://datatracker.ietf.org/doc/html/rfc4648#section-4
|
| :raises: :class:`~google.cloud.exceptions.GoogleCloudError`
| if the upload response returns an error status.
|
| upload_from_filename(self, filename, content_type=None, client=None, predefined_acl=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='auto', retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, crc32c_checksum_value=None)
| Upload this blob's contents from the content of a named file.
|
| The content type of the upload will be determined in order
| of precedence:
|
| - The value passed in to this method (if not :data:`None`)
| - The value stored on the current blob
| - The value given by ``mimetypes.guess_type``
| - The default value ('application/octet-stream')
|
| .. note::
| The effect of uploading to an existing blob depends on the
| "versioning" and "lifecycle" policies defined on the blob's
| bucket. In the absence of those policies, upload will
| overwrite any existing contents.
|
| See the [`object versioning`](https://cloud.google.com/storage/docs/object-versioning)
| and [`lifecycle`](https://cloud.google.com/storage/docs/lifecycle)
| API documents for details.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| See a [code sample](https://cloud.google.com/storage/docs/samples/storage-upload-encrypted-file#storage_upload_encrypted_file-python)
| to upload a file with a
| [`customer-supplied encryption key`](https://cloud.google.com/storage/docs/encryption#customer-supplied).
|
| :type filename: str
| :param filename: The path to the file.
|
| :type content_type: str
| :param content_type: (Optional) Type of content being uploaded.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type predefined_acl: str
| :param predefined_acl: (Optional) Predefined access control list
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type checksum: str
| :param checksum:
| (Optional) The type of checksum to compute to verify
| the integrity of the object. If the upload is completed in a single
| request, the checksum will be entirely precomputed and the remote
| server will handle verification and error handling. If the upload
| is too large and must be transmitted in multiple requests, the
| checksum will be incrementally computed and the client will handle
| verification and error handling, raising
| google.cloud.storage.exceptions.DataCorruption on a mismatch and
| attempting to delete the corrupted file. 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.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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_generation_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 crc32c_checksum_value: str
| :param crc32c_checksum_value: (Optional) This should be the checksum of
| the entire contents of `filename`. Applicable while uploading object
| greater than `_MAX_MULTIPART_SIZE` bytes.
|
| It can be obtained by running
|
| `gcloud storage hash /path/to/your/file`
|
| or
|
| .. code-block:: python
|
| import google_crc32c
| import base64
|
| data = b"Hello, world!"
| crc32c_int = google_crc32c.value(data)
| crc32c_hex = f"{crc32c_int:08x}"
| crc32c_bytes = crc32c_int.to_bytes(4, "big")
| base64_encoded = base64.b64encode(crc32c_bytes)
| crc32c_base64 = base64_encoded.decode("utf-8")
|
| print(crc32c_base64)
|
| Above code block prints 8 char string of base64 encoded big-endian
| bytes of 32 bit CRC32c integer.
|
| More details on CRC32c can be found in Appendix B:
| https://datatracker.ietf.org/doc/html/rfc4960#appendix-B and
| base64: https://datatracker.ietf.org/doc/html/rfc4648#section-4
|
| upload_from_string(self, data, content_type='text/plain', client=None, predefined_acl=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='auto', retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, crc32c_checksum_value=None)
| Upload contents of this blob from the provided string.
|
| .. note::
| The effect of uploading to an existing blob depends on the
| "versioning" and "lifecycle" policies defined on the blob's
| bucket. In the absence of those policies, upload will
| overwrite any existing contents.
|
| See the [`object versioning`](https://cloud.google.com/storage/docs/object-versioning)
| and [`lifecycle`](https://cloud.google.com/storage/docs/lifecycle)
| API documents for details.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type data: bytes or str
| :param data:
| The data to store in this blob. If the value is text, it will be
| encoded as UTF-8.
|
| :type content_type: str
| :param content_type:
| (Optional) Type of content being uploaded. Defaults to
| ``'text/plain'``.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type predefined_acl: str
| :param predefined_acl: (Optional) Predefined access control list
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type checksum: str
| :param checksum:
| (Optional) The type of checksum to compute to verify
| the integrity of the object. If the upload is completed in a single
| request, the checksum will be entirely precomputed and the remote
| server will handle verification and error handling. If the upload
| is too large and must be transmitted in multiple requests, the
| checksum will be incrementally computed and the client will handle
| verification and error handling, raising
| google.cloud.storage.exceptions.DataCorruption on a mismatch and
| attempting to delete the corrupted file. 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.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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_generation_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 crc32c_checksum_value: str
| :param crc32c_checksum_value: (Optional) This should be the checksum of
| the entire contents of `file_obj`. Applicable while uploading object
| greater than `_MAX_MULTIPART_SIZE` bytes.
|
| It can be obtained by running
|
| `gcloud storage hash /path/to/your/file`
|
| or
|
| .. code-block:: python
|
| import google_crc32c
| import base64
|
| data = b"Hello, world!"
| crc32c_int = google_crc32c.value(data)
| crc32c_hex = f"{crc32c_int:08x}"
| crc32c_bytes = crc32c_int.to_bytes(4, "big")
| base64_encoded = base64.b64encode(crc32c_bytes)
| crc32c_base64 = base64_encoded.decode("utf-8")
|
| print(crc32c_base64)
|
| Above code block prints 8 char string of base64 encoded big-endian
| bytes of 32 bit CRC32c integer.
|
| More details on CRC32c can be found in Appendix B:
| https://datatracker.ietf.org/doc/html/rfc4960#appendix-B and
| base64: https://datatracker.ietf.org/doc/html/rfc4648#section-4
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_string(uri, client=None)
| (Deprecated) Get a constructor for blob object by URI.
|
| .. note::
| Deprecated alias for :meth:`from_uri`.
|
| .. code-block:: python
|
| from google.cloud import storage
| from google.cloud.storage.blob import Blob
| client = storage.Client()
| blob = Blob.from_string("gs://bucket/object", client=client)
|
| :type uri: str
| :param uri: The blob uri following a gs://bucket/object pattern.
| Both a bucket and object name is required to construct a blob object.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. Application code should
| *always* pass ``client``.
|
| :rtype: :class:`google.cloud.storage.blob.Blob`
| :returns: The blob object created.
|
| from_uri(uri, client=None)
| Get a constructor for blob object by URI.
|
| .. code-block:: python
|
| from google.cloud import storage
| from google.cloud.storage.blob import Blob
| client = storage.Client()
| blob = Blob.from_uri("gs://bucket/object", client=client)
|
| :type uri: str
| :param uri: The blob uri following a gs://bucket/object pattern.
| Both a bucket and object name is required to construct a blob object.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. Application code should
| *always* pass ``client``.
|
| :rtype: :class:`google.cloud.storage.blob.Blob`
| :returns: The blob object created.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| path_helper(bucket_path, blob_name)
| Relative URL path for a blob.
|
| :type bucket_path: str
| :param bucket_path: The URL path for a bucket.
|
| :type blob_name: str
| :param blob_name: The name of the blob.
|
| :rtype: str
| :returns: The relative URL path for ``blob_name``.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| acl
| Create our ACL on demand.
|
| bucket
| Bucket which contains the object.
|
| :rtype: :class:`~google.cloud.storage.bucket.Bucket`
| :returns: The object's bucket.
|
| client
| The client bound to this blob.
|
| component_count
| Number of underlying components that make up this object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: int or ``NoneType``
| :returns: The component count (in case of a composed object) or
| ``None`` if the blob's resource has not been loaded from
| the server. This property will not be set on objects
| not created via ``compose``.
|
| etag
| Retrieve the ETag for the object.
|
| See [`RFC 2616 (etags)`](https://tools.ietf.org/html/rfc2616#section-3.11) and
| [`API reference docs`](https://cloud.google.com/storage/docs/json_api/v1/objects).
|
| :rtype: str or ``NoneType``
| :returns: The blob etag or ``None`` if the blob's resource has not
| been loaded from the server.
|
| finalized_time
| If this object has been soft-deleted, returns the time at which it will be permanently deleted.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns:
| (readonly) The time that the object will be permanently deleted.
| Note this property is only set for soft-deleted objects.
|
| generation
| Retrieve the generation for the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: int or ``NoneType``
| :returns: The generation of the blob or ``None`` if the blob's
| resource has not been loaded from the server.
|
| hard_delete_time
| If this object has been soft-deleted, returns the time at which it will be permanently deleted.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns:
| (readonly) The time that the object will be permanently deleted.
| Note this property is only set for soft-deleted objects.
|
| id
| Retrieve the ID for the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| The ID consists of the bucket name, object name, and generation number.
|
| :rtype: str or ``NoneType``
| :returns: The ID of the blob or ``None`` if the blob's
| resource has not been loaded from the server.
|
| media_link
| Retrieve the media download URI for the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: str or ``NoneType``
| :returns: The media link for the blob or ``None`` if the blob's
| resource has not been loaded from the server.
|
| metageneration
| Retrieve the metageneration for the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: int or ``NoneType``
| :returns: The metageneration of the blob or ``None`` if the blob's
| resource has not been loaded from the server.
|
| owner
| Retrieve info about the owner of the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: dict or ``NoneType``
| :returns: Mapping of owner's role/ID, or ``None`` if the blob's
| resource has not been loaded from the server.
|
| path
| Getter property for the URL path to this Blob.
|
| :rtype: str
| :returns: The URL path to this Blob.
|
| public_url
| The public URL for this blob.
|
| Use :meth:`make_public` to enable anonymous access via the returned
| URL.
|
| :rtype: `string`
| :returns: The public URL for this blob.
|
| retention
| Retrieve the retention configuration for this object.
|
| :rtype: :class:`Retention`
| :returns: an instance for managing the object's retention configuration.
|
| retention_expiration_time
| Retrieve timestamp at which the object's retention period expires.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the property is not set locally.
|
| self_link
| Retrieve the URI for the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: str or ``NoneType``
| :returns: The self link for the blob or ``None`` if the blob's
| resource has not been loaded from the server.
|
| size
| Size of the object, in bytes.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: int or ``NoneType``
| :returns: The size of the blob or ``None`` if the blob's
| resource has not been loaded from the server.
|
| soft_delete_time
| If this object has been soft-deleted, returns the time at which it became soft-deleted.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns:
| (readonly) The time that the object became soft-deleted.
| Note this property is only set for soft-deleted objects.
|
| time_created
| Retrieve the timestamp at which the object was created.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the blob's resource has not been loaded from
| the server (see :meth:`reload`).
|
| time_deleted
| Retrieve the timestamp at which the object was deleted.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the blob's resource has not been loaded from
| the server (see :meth:`reload`). If the blob has
| not been deleted, this will never be set.
|
| updated
| Retrieve the timestamp at which the object was updated.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the blob's resource has not been loaded from
| the server (see :meth:`reload`).
|
| user_project
| Project ID billed for API requests made via this blob.
|
| Derived from bucket's value.
|
| :rtype: str
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| cache_control
| Scalar property getter.
|
| chunk_size
| Get the blob's default chunk size.
|
| :rtype: int or ``NoneType``
| :returns: The current blob's chunk size, if it is set.
|
| content_disposition
| Scalar property getter.
|
| content_encoding
| Scalar property getter.
|
| content_language
| Scalar property getter.
|
| content_type
| Scalar property getter.
|
| contexts
| Retrieve the contexts for this object.
|
| :rtype: :class:`ObjectContexts`
| :returns: an instance for managing the object's contexts.
|
| crc32c
| Scalar property getter.
|
| custom_time
| Retrieve the custom time for the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the blob's resource has not been loaded from
| the server (see :meth:`reload`).
|
| encryption_key
| Retrieve the customer-supplied encryption key for the object.
|
| :rtype: bytes or ``NoneType``
| :returns:
| The encryption key or ``None`` if no customer-supplied encryption key was used,
| or the blob's resource has not been loaded from the server.
|
| event_based_hold
| Scalar property getter.
|
| kms_key_name
| Resource name of Cloud KMS key used to encrypt the blob's contents.
|
| :rtype: str or ``NoneType``
| :returns:
| The resource name or ``None`` if no Cloud KMS key was used,
| or the blob's resource has not been loaded from the server.
|
| md5_hash
| Scalar property getter.
|
| metadata
| Retrieve arbitrary/application specific metadata for the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :setter: Update arbitrary/application specific metadata for the
| object.
| :getter: Retrieve arbitrary/application specific metadata for
| the object.
|
| :rtype: dict or ``NoneType``
| :returns: The metadata associated with the blob or ``None`` if the
| property is not set.
|
| storage_class
| Scalar property getter.
|
| temporary_hold
| Scalar property getter.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| STORAGE_CLASSES = ('STANDARD', 'NEARLINE', 'COLDLINE', 'ARCHIVE', 'MUL...
|
| ----------------------------------------------------------------------
| Methods inherited from google.cloud.storage._helpers._PropertyMixin:
|
| patch(self, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, override_unlocked_retention=False)
| Sends all changed properties in a PATCH request.
|
| Updates the ``_properties`` with the response from the backend.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: the client to use. If not passed, falls back to the
| ``client`` stored on the current object.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type override_unlocked_retention: bool
| :param override_unlocked_retention:
| (Optional) override_unlocked_retention must be set to True if the operation includes
| a retention property that changes the mode from Unlocked to Locked, reduces the
| retainUntilTime, or removes the retention configuration from the object. See:
| https://cloud.google.com/storage/docs/json_api/v1/objects/patch
|
| reload(self, client=None, projection='noAcl', if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, soft_deleted=None)
| Reload properties from Cloud Storage.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: the client to use. If not passed, falls back to the
| ``client`` stored on the current object.
|
| :type projection: str
| :param projection: (Optional) If used, must be 'full' or 'noAcl'.
| Defaults to ``'noAcl'``. Specifies the set of
| properties to return.
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match: (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]])
| :param if_etag_not_match: (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type soft_deleted: bool
| :param soft_deleted:
| (Optional) If True, looks for a soft-deleted object. Will only return
| the object metadata if the object exists and is in a soft-deleted state.
| :attr:`generation` is required to be set on the blob if ``soft_deleted`` is set to True.
| See: https://cloud.google.com/storage/docs/soft-delete
|
| update(self, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>, override_unlocked_retention=False)
| Sends all properties in a PUT request.
|
| Updates the ``_properties`` with the response from the backend.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: the client to use. If not passed, falls back to the
| ``client`` stored on the current object.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type override_unlocked_retention: bool
| :param override_unlocked_retention:
| (Optional) override_unlocked_retention must be set to True if the operation includes
| a retention property that changes the mode from Unlocked to Locked, reduces the
| retainUntilTime, or removes the retention configuration from the object. See:
| https://cloud.google.com/storage/docs/json_api/v1/objects/patch
|
| ----------------------------------------------------------------------
| Data descriptors inherited from google.cloud.storage._helpers._PropertyMixin:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
google-cloud-storage.Bucket
Python Library Documentation: class Bucket in module google.cloud.storage.bucket
class Bucket(google.cloud.storage._helpers._PropertyMixin)
| Bucket(client, name=None, user_project=None, generation=None)
|
| A class representing a Bucket on Cloud Storage.
|
| :type client: :class:`google.cloud.storage.client.Client`
| :param client: A client which holds credentials and project configuration
| for the bucket (which requires a project).
|
| :type name: str
| :param name: The name of the bucket. Bucket names must start and end with a
| number or letter.
|
| :type user_project: str
| :param user_project: (Optional) the project ID to be billed for API
| requests made via this instance.
|
| :type generation: int
| :param generation: (Optional) If present, selects a specific revision of
| this bucket.
|
| Method resolution order:
| Bucket
| google.cloud.storage._helpers._PropertyMixin
| builtins.object
|
| Methods defined here:
|
| __init__(self, client, name=None, user_project=None, generation=None)
| property :attr:`name`
| Get the bucket's name.
|
| __repr__(self)
| Return repr(self).
|
| add_lifecycle_abort_incomplete_multipart_upload_rule(self, **kw)
| Add a "abort incomplete multipart upload" rule to lifecycle rules.
|
| .. note::
| The "age" lifecycle condition is the only supported condition
| for this rule.
|
| This defines a [lifecycle configuration](https://cloud.google.com/storage/docs/lifecycle),
| which is set on the bucket. For the general format of a lifecycle configuration, see the
| [bucket resource representation for JSON](https://cloud.google.com/storage/docs/json_api/v1/buckets).
|
| :type kw: dict
| :params kw: arguments passed to :class:`LifecycleRuleConditions`.
|
| add_lifecycle_delete_rule(self, **kw)
| Add a "delete" rule to lifecycle rules configured for this bucket.
|
| This defines a [lifecycle configuration](https://cloud.google.com/storage/docs/lifecycle),
| which is set on the bucket. For the general format of a lifecycle configuration, see the
| [bucket resource representation for JSON](https://cloud.google.com/storage/docs/json_api/v1/buckets).
| See also a [code sample](https://cloud.google.com/storage/docs/samples/storage-enable-bucket-lifecycle-management#storage_enable_bucket_lifecycle_management-python).
|
| :type kw: dict
| :params kw: arguments passed to :class:`LifecycleRuleConditions`.
|
| add_lifecycle_set_storage_class_rule(self, storage_class, **kw)
| Add a "set storage class" rule to lifecycle rules.
|
| This defines a [lifecycle configuration](https://cloud.google.com/storage/docs/lifecycle),
| which is set on the bucket. For the general format of a lifecycle configuration, see the
| [bucket resource representation for JSON](https://cloud.google.com/storage/docs/json_api/v1/buckets).
|
| :type storage_class: str, one of :attr:`STORAGE_CLASSES`.
| :param storage_class: new storage class to assign to matching items.
|
| :type kw: dict
| :params kw: arguments passed to :class:`LifecycleRuleConditions`.
|
| blob(self, blob_name, chunk_size=None, encryption_key=None, kms_key_name=None, generation=None)
| Factory constructor for blob object.
|
| .. note::
| This will not make an HTTP request; it simply instantiates
| a blob object owned by this bucket.
|
| :type blob_name: str
| :param blob_name: The name of the blob to be instantiated.
|
| :type chunk_size: int
| :param chunk_size: The size of a chunk of data whenever iterating
| (in bytes). This must be a multiple of 256 KB per
| the API specification.
|
| :type encryption_key: bytes
| :param encryption_key:
| (Optional) 32 byte encryption key for customer-supplied encryption.
|
| :type kms_key_name: str
| :param kms_key_name:
| (Optional) Resource name of KMS key used to encrypt blob's content.
|
| :type generation: long
| :param generation: (Optional) If present, selects a specific revision of
| this object.
|
| :type crc32c_checksum: str
| :param crc32c_checksum:
| (Optional) If set, the CRC32C checksum of the blob's content.
| CRC32c checksum, as described in RFC 4960, Appendix B; encoded using
| base64 in big-endian byte order. See
| Apenndix B: https://datatracker.ietf.org/doc/html/rfc4960#appendix-B
| base64: https://datatracker.ietf.org/doc/html/rfc4648#section-4
|
| :rtype: :class:`google.cloud.storage.blob.Blob`
| :returns: The blob object created.
|
| clear_lifecycle_rules(self)
| Clear lifecycle rules configured for this bucket.
|
| See https://cloud.google.com/storage/docs/lifecycle and
| https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| clear_lifecyle_rules(self)
| Deprecated alias for clear_lifecycle_rules.
|
| configure_website(self, main_page_suffix=None, not_found_page=None)
| Configure website-related properties.
|
| See https://cloud.google.com/storage/docs/static-website
|
| .. note::
| This configures the bucket's website-related properties,controlling how
| the service behaves when accessing bucket contents as a web site.
| See [tutorials](https://cloud.google.com/storage/docs/hosting-static-website) and
| [code samples](https://cloud.google.com/storage/docs/samples/storage-define-bucket-website-configuration#storage_define_bucket_website_configuration-python)
| for more information.
|
| :type main_page_suffix: str
| :param main_page_suffix: The page to use as the main page
| of a directory.
| Typically something like index.html.
|
| :type not_found_page: str
| :param not_found_page: The file to use when a page isn't found.
|
| copy_blob(self, blob, destination_bucket, new_name=None, client=None, preserve_acl=True, source_generation=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, if_source_generation_match=None, if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2CF29F40>, destination_contexts=None)
| Copy the given blob to the given bucket, optionally with a new name.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/objects/copy)
| and a [code sample](https://cloud.google.com/storage/docs/samples/storage-copy-file#storage_copy_file-python).
|
| :type blob: :class:`google.cloud.storage.blob.Blob`
| :param blob: The blob to be copied.
|
| :type destination_bucket: :class:`google.cloud.storage.bucket.Bucket`
| :param destination_bucket: The bucket into which the blob should be
| copied.
|
| :type new_name: str
| :param new_name: (Optional) The new name for the copied file.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type preserve_acl: bool
| :param preserve_acl: DEPRECATED. This argument is not functional!
| (Optional) Copies ACL from old blob to new blob.
| Default: True.
| Note that ``preserve_acl`` is not supported in a
| ``Batch`` context.
|
| :type source_generation: long
| :param source_generation: (Optional) The generation of the blob to be
| copied.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_source_generation_match: long
| :param if_source_generation_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation matches the given value.
|
| :type if_source_generation_not_match: long
| :param if_source_generation_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation does not match the given value.
|
| :type if_source_metageneration_match: long
| :param if_source_metageneration_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration matches the given value.
|
| :type if_source_metageneration_not_match: long
| :param if_source_metageneration_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration does not match the given value.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC.
| The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
| policy which will only enable retries if ``if_generation_match`` or ``generation``
| is set, in order to ensure requests are idempotent before retrying them.
| Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
| to enable retries regardless of generation precondition setting.
| See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| :type destination_contexts: :class:`~google.cloud.storage.blob.ObjectContexts` or dict
| :param destination_contexts:
| (Optional) New contexts to set for the destination object.
| See: https://docs.cloud.google.com/storage/docs/use-object-contexts#manage_object_contexts_during_object_operations
| :rtype: :class:`google.cloud.storage.blob.Blob`
| :returns: The new Blob.
|
| create(self, client=None, project=None, location=None, predefined_acl=None, predefined_default_object_acl=None, enable_object_retention=False, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Creates current bucket.
|
| If the bucket already exists, will raise
| :class:`google.cloud.exceptions.Conflict`.
|
| This implements "storage.buckets.insert".
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type project: str
| :param project: (Optional) The project under which the bucket is to
| be created. If not passed, uses the project set on
| the client.
| :raises ValueError: if ``project`` is None and client's
| :attr:`project` is also None.
|
| :type location: str
| :param location: (Optional) The location of the bucket. If not passed,
| the default location, US, will be used. See
| https://cloud.google.com/storage/docs/bucket-locations
|
| :type predefined_acl: str
| :param predefined_acl:
| (Optional) Name of predefined ACL to apply to bucket. See:
| https://cloud.google.com/storage/docs/access-control/lists#predefined-acl
|
| :type predefined_default_object_acl: str
| :param predefined_default_object_acl:
| (Optional) Name of predefined ACL to apply to bucket's objects. See:
| https://cloud.google.com/storage/docs/access-control/lists#predefined-acl
|
| :type enable_object_retention: bool
| :param enable_object_retention:
| (Optional) Whether object retention should be enabled on this bucket. See:
| https://cloud.google.com/storage/docs/object-lock
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| delete(self, force=False, client=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Delete this bucket.
|
| The bucket **must** be empty in order to submit a delete request. If
| ``force=True`` is passed, this will first attempt to delete all the
| objects / blobs in the bucket (i.e. try to empty the bucket).
|
| If the bucket doesn't exist, this will raise
| :class:`google.cloud.exceptions.NotFound`. If the bucket is not empty
| (and ``force=False``), will raise :class:`google.cloud.exceptions.Conflict`.
|
| If ``force=True`` and the bucket contains more than 256 objects / blobs
| this will cowardly refuse to delete the objects (or the bucket). This
| is to prevent accidental bucket deletion and to prevent extremely long
| runtime of this method. Also note that ``force=True`` is not supported
| in a ``Batch`` context.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type force: bool
| :param force: If True, empties the bucket's objects then deletes it.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration matches the given value.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration does not match the given value.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :raises: :class:`ValueError` if ``force`` is ``True`` and the bucket
| contains more than 256 objects / blobs.
|
| delete_blob(self, blob_name, client=None, generation=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Deletes a blob from the current bucket.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type blob_name: str
| :param blob_name: A blob name to delete.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type generation: long
| :param generation: (Optional) If present, permanently deletes a specific
| revision of this object.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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_generation_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.
|
| :raises: :class:`google.cloud.exceptions.NotFound` Raises a NotFound
| if the blob isn't found. To suppress
| the exception, use :meth:`delete_blobs` by passing a no-op
| ``on_error`` callback.
|
| delete_blobs(self, blobs, on_error=None, client=None, preserve_generation=False, timeout=60, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Deletes a list of blobs from the current bucket.
|
| Uses :meth:`delete_blob` to delete each individual blob.
|
| By default, any generation information in the list of blobs is ignored, and the
| live versions of all blobs are deleted. Set `preserve_generation` to True
| if blob generation should instead be propagated from the list of blobs.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type blobs: list
| :param blobs: A list of :class:`~google.cloud.storage.blob.Blob`-s or
| blob names to delete.
|
| :type on_error: callable
| :param on_error: (Optional) Takes single argument: ``blob``.
| Called once for each blob raising
| :class:`~google.cloud.exceptions.NotFound`;
| otherwise, the exception is propagated.
| Note that ``on_error`` is not supported in a ``Batch`` context.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type preserve_generation: bool
| :param preserve_generation: (Optional) Deletes only the generation specified on the blob object,
| instead of the live version, if set to True. Only :class:~google.cloud.storage.blob.Blob
| objects can have their generation set in this way.
| Default: False.
|
| :type if_generation_match: list of long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
| Note that the length of the list must match the length of
| The list must match ``blobs`` item-to-item.
|
| :type if_generation_not_match: list of long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
| The list must match ``blobs`` item-to-item.
|
| :type if_metageneration_match: list of long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
| The list must match ``blobs`` item-to-item.
|
| :type if_metageneration_not_match: list of long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
| The list must match ``blobs`` item-to-item.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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_generation_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.
|
| :raises: :class:`~google.cloud.exceptions.NotFound` (if
| `on_error` is not passed).
|
| disable_logging(self)
| Disable access logging for this bucket.
|
| See https://cloud.google.com/storage/docs/access-logs#disabling
|
| disable_website(self)
| Disable the website configuration for this bucket.
|
| This is really just a shortcut for setting the website-related
| attributes to ``None``.
|
| enable_logging(self, bucket_name, object_prefix='')
| Enable access logging for this bucket.
|
| See https://cloud.google.com/storage/docs/access-logs
|
| :type bucket_name: str
| :param bucket_name: name of bucket in which to store access logs
|
| :type object_prefix: str
| :param object_prefix: prefix for access log filenames
|
| exists(self, client=None, timeout=60, if_etag_match=None, if_etag_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Determines whether or not this bucket exists.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match: (Optional) Make the operation conditional on whether the
| bucket's current ETag matches the given value.
|
| :type if_etag_not_match: Union[str, Set[str]])
| :param if_etag_not_match: (Optional) Make the operation conditional on whether the
| bucket's current ETag does not match the given value.
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| bucket's current metageneration matches the given value.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| bucket's current metageneration does not match the given value.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: bool
| :returns: True if the bucket exists in Cloud Storage.
|
| generate_signed_url(self, expiration=None, api_access_endpoint=None, method='GET', headers=None, query_parameters=None, client=None, credentials=None, version=None, virtual_hosted_style=False, bucket_bound_hostname=None, scheme='http')
| Generates a signed URL for this bucket.
|
| .. note::
|
| If you are on Google Compute Engine, you can't generate a signed
| URL using GCE service account. If you'd like to be able to generate
| a signed URL from GCE, you can use a standard service account from a
| JSON file rather than a GCE service account.
|
| If you have a bucket that you want to allow access to for a set
| amount of time, you can use this method to generate a URL that
| is only valid within a certain time period.
|
| If ``bucket_bound_hostname`` is set as an argument of :attr:`api_access_endpoint`,
| ``https`` works only if using a ``CDN``.
|
| :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
| :param expiration: Point in time when the signed URL should expire. If
| a ``datetime`` instance is passed without an explicit
| ``tzinfo`` set, it will be assumed to be ``UTC``.
|
| :type api_access_endpoint: str
| :param api_access_endpoint: (Optional) URI base, for instance
| "https://storage.googleapis.com". If not specified, the client's
| api_endpoint will be used. Incompatible with bucket_bound_hostname.
|
| :type method: str
| :param method: The HTTP verb that will be used when requesting the URL.
|
| :type headers: dict
| :param headers:
| (Optional) Additional HTTP headers to be included as part of the
| signed URLs. See:
| https://cloud.google.com/storage/docs/xml-api/reference-headers
| Requests using the signed URL *must* pass the specified header
| (name and value) with each request for the URL.
|
| :type query_parameters: dict
| :param query_parameters:
| (Optional) Additional query parameters to be included as part of the
| signed URLs. See:
| https://cloud.google.com/storage/docs/xml-api/reference-headers#query
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the blob's bucket.
|
| :type credentials: :class:`google.auth.credentials.Credentials` or
| :class:`NoneType`
| :param credentials: The authorization credentials to attach to requests.
| These credentials identify this application to the service.
| If none are specified, the client will attempt to ascertain
| the credentials from the environment.
|
| :type version: str
| :param version: (Optional) The version of signed credential to create.
| Must be one of 'v2' | 'v4'.
|
| :type virtual_hosted_style: bool
| :param virtual_hosted_style:
| (Optional) If true, then construct the URL relative the bucket's
| virtual hostname, e.g., '<bucket-name>.storage.googleapis.com'.
| Incompatible with bucket_bound_hostname.
|
| :type bucket_bound_hostname: str
| :param bucket_bound_hostname:
| (Optional) If passed, then construct the URL relative to the bucket-bound hostname.
| Value can be a bare or with scheme, e.g., 'example.com' or 'http://example.com'.
| Incompatible with api_access_endpoint and virtual_hosted_style.
| See: https://cloud.google.com/storage/docs/request-endpoints#cname
|
| :type scheme: str
| :param scheme:
| (Optional) If ``bucket_bound_hostname`` is passed as a bare hostname, use
| this value as the scheme. ``https`` will work only when using a CDN.
| Defaults to ``"http"``.
|
| :raises: :exc:`ValueError` when version is invalid or mutually exclusive arguments are used.
| :raises: :exc:`TypeError` when expiration is not a valid type.
| :raises: :exc:`AttributeError` if credentials is not an instance
| of :class:`google.auth.credentials.Signing`.
|
| :rtype: str
| :returns: A signed URL you can use to access the resource
| until expiration.
|
| generate_upload_policy(self, conditions, expiration=None, client=None)
| Create a signed upload policy for uploading objects.
|
| This method generates and signs a policy document. You can use
| [`policy documents`](https://cloud.google.com/storage/docs/xml-api/post-object-forms)
| to allow visitors to a website to upload files to
| Google Cloud Storage without giving them direct write access.
| See a [code sample](https://cloud.google.com/storage/docs/xml-api/post-object-forms#python).
|
| :type expiration: datetime
| :param expiration: (Optional) Expiration in UTC. If not specified, the
| policy will expire in 1 hour.
|
| :type conditions: list
| :param conditions: A list of conditions as described in the
| `policy documents` documentation.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :rtype: dict
| :returns: A dictionary of (form field name, form field value) of form
| fields that should be added to your HTML upload form in order
| to attach the signature.
|
| get_blob(self, blob_name, client=None, encryption_key=None, generation=None, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, soft_deleted=None, **kwargs)
| Get a blob object by name.
|
| See a [code sample](https://cloud.google.com/storage/docs/samples/storage-get-metadata#storage_get_metadata-python)
| on how to retrieve metadata of an object.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type blob_name: str
| :param blob_name: The name of the blob to retrieve.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type encryption_key: bytes
| :param encryption_key:
| (Optional) 32 byte encryption key for customer-supplied encryption.
| See
| https://cloud.google.com/storage/docs/encryption#customer-supplied.
|
| :type generation: long
| :param generation:
| (Optional) If present, selects a specific revision of this object.
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match:
| (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]]
| :param if_etag_not_match:
| (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type soft_deleted: bool
| :param soft_deleted:
| (Optional) If True, looks for a soft-deleted object. Will only return
| the object metadata if the object exists and is in a soft-deleted state.
| Object ``generation`` is required if ``soft_deleted`` is set to True.
| See: https://cloud.google.com/storage/docs/soft-delete
|
| :param kwargs: Keyword arguments to pass to the
| :class:`~google.cloud.storage.blob.Blob` constructor.
|
| :rtype: :class:`google.cloud.storage.blob.Blob` or None
| :returns: The blob object if it exists, otherwise None.
|
| get_iam_policy(self, client=None, requested_policy_version=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Retrieve the IAM policy for the bucket.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/buckets/getIamPolicy)
| and a [code sample](https://cloud.google.com/storage/docs/samples/storage-view-bucket-iam-members#storage_view_bucket_iam_members-python).
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type requested_policy_version: int or ``NoneType``
| :param requested_policy_version: (Optional) The version of IAM policies to request.
| If a policy with a condition is requested without
| setting this, the server will return an error.
| This must be set to a value of 3 to retrieve IAM
| policies containing conditions. This is to prevent
| client code that isn't aware of IAM conditions from
| interpreting and modifying policies incorrectly.
| The service might return a policy with version lower
| than the one that was requested, based on the
| feature syntax in the policy fetched.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: :class:`google.api_core.iam.Policy`
| :returns: the policy instance, based on the resource returned from
| the ``getIamPolicy`` API request.
|
| get_logging(self)
| Return info about access logging for this bucket.
|
| See https://cloud.google.com/storage/docs/access-logs#status
|
| :rtype: dict or None
| :returns: a dict w/ keys, ``logBucket`` and ``logObjectPrefix``
| (if logging is enabled), or None (if not).
|
| get_notification(self, notification_id, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Get Pub / Sub notification for this bucket.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/notifications/get)
| and a [code sample](https://cloud.google.com/storage/docs/samples/storage-print-pubsub-bucket-notification#storage_print_pubsub_bucket_notification-python).
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type notification_id: str
| :param notification_id: The notification id to retrieve the notification configuration.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: :class:`.BucketNotification`
| :returns: notification instance.
|
| list_blobs(self, max_results=None, page_token=None, prefix=None, delimiter=None, start_offset=None, end_offset=None, include_trailing_delimiter=None, versions=None, projection='noAcl', fields=None, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, match_glob=None, include_folders_as_prefixes=None, soft_deleted=None, page_size=None, filter_=None)
| Return an iterator used to find blobs in the bucket.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type max_results: int
| :param max_results:
| (Optional) The maximum number of blobs to return.
|
| :type page_token: str
| :param page_token:
| (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.
|
| :type prefix: str
| :param prefix: (Optional) Prefix used to filter blobs.
|
| :type delimiter: str
| :param delimiter: (Optional) Delimiter, used with ``prefix`` to
| emulate hierarchy.
|
| :type start_offset: str
| :param start_offset:
| (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).
|
| :type end_offset: str
| :param end_offset:
| (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).
|
| :type include_trailing_delimiter: boolean
| :param include_trailing_delimiter:
| (Optional) If true, objects that end in exactly one instance of
| ``delimiter`` will have their metadata included in ``items`` in
| addition to ``prefixes``.
|
| :type versions: bool
| :param versions: (Optional) Whether object versions should be returned
| as separate blobs.
|
| :type projection: str
| :param projection: (Optional) If used, must be 'full' or 'noAcl'.
| Defaults to ``'noAcl'``. Specifies the set of
| properties to return.
|
| :type fields: str
| :param fields:
| (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
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type match_glob: str
| :param match_glob:
| (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
|
| :type 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
|
| :type soft_deleted: bool
| :param soft_deleted:
| (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
|
| :type filter_: str or None
| :param filter_:
| (Optional) Filter string used to filter objects. See:
| https://docs.cloud.google.com/storage/docs/listing-objects#filter-by-object-contexts-syntax
|
| :type page_size: int
| :param page_size:
| (Optional) Maximum number of blobs to return in each page.
| Defaults to a value set by the API.
|
| :rtype: :class:`~google.api_core.page_iterator.Iterator`
| :returns: Iterator of all :class:`~google.cloud.storage.blob.Blob`
| in this bucket matching the arguments.
|
| list_notifications(self, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| List Pub / Sub notifications for this bucket.
|
| See:
| https://cloud.google.com/storage/docs/json_api/v1/notifications/list
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: list of :class:`.BucketNotification`
| :returns: notification instances
|
| lock_retention_policy(self, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Lock the bucket's retention policy.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the blob's bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :raises ValueError:
| if the bucket has no metageneration (i.e., new or never reloaded);
| if the bucket has no retention policy assigned;
| if the bucket's retention policy is already locked.
|
| make_private(self, recursive=False, future=False, client=None, timeout=60, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Update bucket's ACL, revoking read access for anonymous users.
|
| :type recursive: bool
| :param recursive: If True, this will make all blobs inside the bucket
| private as well.
|
| :type future: bool
| :param future: If True, this will make all objects created in the
| future private as well.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration matches the given value.
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration does not match the given value.
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :raises ValueError:
| If ``recursive`` is True, and the bucket contains more than 256
| blobs. This is to prevent extremely long runtime of this
| method. For such buckets, iterate over the blobs returned by
| :meth:`list_blobs` and call
| :meth:`~google.cloud.storage.blob.Blob.make_private`
| for each blob.
|
| make_public(self, recursive=False, future=False, client=None, timeout=60, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Update bucket's ACL, granting read access to anonymous users.
|
| :type recursive: bool
| :param recursive: If True, this will make all blobs inside the bucket
| public as well.
|
| :type future: bool
| :param future: If True, this will make all objects created in the
| future public as well.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration matches the given value.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration does not match the given value.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :raises ValueError:
| If ``recursive`` is True, and the bucket contains more than 256
| blobs. This is to prevent extremely long runtime of this
| method. For such buckets, iterate over the blobs returned by
| :meth:`list_blobs` and call
| :meth:`~google.cloud.storage.blob.Blob.make_public`
| for each blob.
|
| move_blob(self, blob, new_name, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, if_source_generation_match=None, if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2CF29F40>)
| Move a blob to a new name atomically.
|
| If :attr:`user_project` is set on the bucket, bills the API request to that project.
|
| :type blob: :class:`google.cloud.storage.blob.Blob`
| :param blob: The blob to be renamed.
|
| :type new_name: str
| :param new_name: The new name for this blob.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type if_generation_match: int
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_generation_not_match: int
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_match: int
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_not_match: int
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_source_generation_match: int
| :param if_source_generation_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation matches the given value.
|
| :type if_source_generation_not_match: int
| :param if_source_generation_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation does not match the given value.
|
| :type if_source_metageneration_match: int
| :param if_source_metageneration_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration matches the given value.
|
| :type if_source_metageneration_not_match: int
| :param if_source_metageneration_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration does not match the given value.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry
| :param retry:
| (Optional) How to retry the RPC.
| See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| :rtype: :class:`Blob`
| :returns: The newly-moved blob.
|
| notification(self, topic_name=None, topic_project=None, custom_attributes=None, event_types=None, blob_name_prefix=None, payload_format='NONE', notification_id=None)
| Factory: create a notification resource for the bucket.
|
| See: :class:`.BucketNotification` for parameters.
|
| :rtype: :class:`.BucketNotification`
|
| patch(self, client=None, timeout=60, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Sends all changed properties in a PATCH request.
|
| Updates the ``_properties`` with the response from the backend.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: the client to use. If not passed, falls back to the
| ``client`` stored on the current object.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration matches the given value.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration does not match the given value.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| reload(self, client=None, projection='noAcl', timeout=60, if_etag_match=None, if_etag_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, soft_deleted=None)
| Reload properties from Cloud Storage.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: the client to use. If not passed, falls back to the
| ``client`` stored on the current object.
|
| :type projection: str
| :param projection: (Optional) If used, must be 'full' or 'noAcl'.
| Defaults to ``'noAcl'``. Specifies the set of
| properties to return.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match: (Optional) Make the operation conditional on whether the
| bucket's current ETag matches the given value.
|
| :type if_etag_not_match: Union[str, Set[str]])
| :param if_etag_not_match: (Optional) Make the operation conditional on whether the
| bucket's current ETag does not match the given value.
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| bucket's current metageneration matches the given value.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| bucket's current metageneration does not match the given value.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type soft_deleted: bool
| :param soft_deleted: (Optional) 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`` must be
| set if ``soft_deleted`` is set to True.
| See: https://cloud.google.com/storage/docs/soft-delete
|
| rename_blob(self, blob, new_name, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, if_source_generation_match=None, if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2CF29F40>)
| Rename the given blob using copy and delete operations.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| Effectively, copies blob to the same bucket with a new name, then
| deletes the blob.
|
| .. warning::
|
| This method will first duplicate the data and then delete the
| old blob. This means that with very large objects renaming
| could be a very (temporarily) costly or a very slow operation.
| If you need more control over the copy and deletion, instead
| use ``google.cloud.storage.blob.Blob.copy_to`` and
| ``google.cloud.storage.blob.Blob.delete`` directly.
|
| Also note that this method is not fully supported in a
| ``Batch`` context.
|
| :type blob: :class:`google.cloud.storage.blob.Blob`
| :param blob: The blob to be renamed.
|
| :type new_name: str
| :param new_name: The new name for this blob.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_source_generation_match: long
| :param if_source_generation_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation matches the given value. Also used in the
| (implied) delete request.
|
| :type if_source_generation_not_match: long
| :param if_source_generation_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation does not match the given value. Also used in
| the (implied) delete request.
|
| :type if_source_metageneration_match: long
| :param if_source_metageneration_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration matches the given value. Also used
| in the (implied) delete request.
|
| :type if_source_metageneration_not_match: long
| :param if_source_metageneration_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration does not match the given value.
| Also used in the (implied) delete request.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC.
| The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
| policy which will only enable retries if ``if_generation_match`` or ``generation``
| is set, in order to ensure requests are idempotent before retrying them.
| Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
| to enable retries regardless of generation precondition setting.
| See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| :rtype: :class:`Blob`
| :returns: The newly-renamed blob.
|
| restore_blob(self, blob_name, client=None, generation=None, copy_source_acl=None, projection=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2CF29F40>)
| Restores a soft-deleted object.
|
| If :attr:`user_project` is set on the bucket, bills the API request to that project.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/objects/restore)
|
| :type blob_name: str
| :param blob_name: The name of the blob to be restored.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type generation: int
| :param generation: Selects the specific revision of the object.
|
| :type copy_source_acl: bool
| :param copy_source_acl: (Optional) If true, copy the soft-deleted object's access controls.
|
| :type projection: str
| :param projection: (Optional) Specifies the set of properties to return.
| If used, must be 'full' or 'noAcl'.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC.
| The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, which
| only restore operations with ``if_generation_match`` or ``generation`` set
| will be retried.
|
| Users can configure non-default retry behavior. A ``None`` value will
| disable retries. A ``DEFAULT_RETRY`` value will enable retries
| even if restore operations are not guaranteed to be idempotent.
| See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| :rtype: :class:`google.cloud.storage.blob.Blob`
| :returns: The restored Blob.
|
| set_iam_policy(self, policy, client=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920980>)
| Update the IAM policy for the bucket.
|
| See
| https://cloud.google.com/storage/docs/json_api/v1/buckets/setIamPolicy
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type policy: :class:`google.api_core.iam.Policy`
| :param policy: policy instance used to update bucket's IAM policy.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: :class:`google.api_core.iam.Policy`
| :returns: the policy instance, based on the resource returned from
| the ``setIamPolicy`` API request.
|
| test_iam_permissions(self, permissions, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| API call: test permissions
|
| See
| https://cloud.google.com/storage/docs/json_api/v1/buckets/testIamPermissions
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type permissions: list of string
| :param permissions: the permissions to check
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: list of string
| :returns: the permissions returned by the ``testIamPermissions`` API
| request.
|
| update(self, client=None, timeout=60, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Sends all properties in a PUT request.
|
| Updates the ``_properties`` with the response from the backend.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: the client to use. If not passed, falls back to the
| ``client`` stored on the current object.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration matches the given value.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration does not match the given value.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_string(uri, client=None)
| Get a constructor for bucket object by URI.
|
| .. note::
| Deprecated alias for :meth:`from_uri`.
|
| .. code-block:: python
|
| from google.cloud import storage
| from google.cloud.storage.bucket import Bucket
| client = storage.Client()
| bucket = Bucket.from_string("gs://bucket", client=client)
|
| :type uri: str
| :param uri: The bucket uri pass to get bucket object.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. Application code should
| *always* pass ``client``.
|
| :rtype: :class:`google.cloud.storage.bucket.Bucket`
| :returns: The bucket object created.
|
| from_uri(uri, client=None)
| Get a constructor for bucket object by URI.
|
| .. code-block:: python
|
| from google.cloud import storage
| from google.cloud.storage.bucket import Bucket
| client = storage.Client()
| bucket = Bucket.from_uri("gs://bucket", client=client)
|
| :type uri: str
| :param uri: The bucket uri pass to get bucket object.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. Application code should
| *always* pass ``client``.
|
| :rtype: :class:`google.cloud.storage.bucket.Bucket`
| :returns: The bucket object created.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| path_helper(bucket_name)
| Relative URL path for a bucket.
|
| :type bucket_name: str
| :param bucket_name: The bucket name in the path.
|
| :rtype: str
| :returns: The relative URL path for ``bucket_name``.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| acl
| Create our ACL on demand.
|
| autoclass_terminal_storage_class_update_time
| The time at which the Autoclass terminal_storage_class field was last updated for this bucket
| :rtype: datetime.datetime or ``NoneType``
| :returns: point-in time at which the bucket's terminal_storage_class is last updated, or ``None`` if the property is not set locally.
|
| autoclass_toggle_time
| Retrieve the toggle time when Autoclaass was last enabled or disabled for the bucket.
| :rtype: datetime.datetime or ``NoneType``
| :returns: point-in time at which the bucket's autoclass is toggled, or ``None`` if the property is not set locally.
|
| client
| The client bound to this bucket.
|
| data_locations
| Retrieve the list of regional locations for custom dual-region buckets.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets and
| https://cloud.google.com/storage/docs/locations
|
| Returns ``None`` if the property has not been set before creation,
| if the bucket's resource has not been loaded from the server,
| or if the bucket is not a dual-regions bucket.
| :rtype: list of str or ``NoneType``
|
| default_object_acl
| Create our defaultObjectACL on demand.
|
| etag
| Retrieve the ETag for the bucket.
|
| See https://tools.ietf.org/html/rfc2616#section-3.11 and
| https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: str or ``NoneType``
| :returns: The bucket etag or ``None`` if the bucket's
| resource has not been loaded from the server.
|
| generation
| Retrieve the generation for the bucket.
|
| :rtype: int or ``NoneType``
| :returns: The generation of the bucket or ``None`` if the bucket's
| resource has not been loaded from the server.
|
| hard_delete_time
| If this bucket has been soft-deleted, returns the time at which it will be permanently deleted.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns:
| (readonly) The time that the bucket will be permanently deleted.
| Note this property is only set for soft-deleted buckets.
|
| iam_configuration
| Retrieve IAM configuration for this bucket.
|
| :rtype: :class:`IAMConfiguration`
| :returns: an instance for managing the bucket's IAM configuration.
|
| id
| Retrieve the ID for the bucket.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: str or ``NoneType``
| :returns: The ID of the bucket or ``None`` if the bucket's
| resource has not been loaded from the server.
|
| location_type
| Retrieve the location type for the bucket.
|
| See https://cloud.google.com/storage/docs/storage-classes
|
| :getter: Gets the the location type for this bucket.
|
| :rtype: str or ``NoneType``
| :returns:
| If set, one of
| :attr:`~google.cloud.storage.constants.MULTI_REGION_LOCATION_TYPE`,
| :attr:`~google.cloud.storage.constants.REGION_LOCATION_TYPE`, or
| :attr:`~google.cloud.storage.constants.DUAL_REGION_LOCATION_TYPE`,
| else ``None``.
|
| metageneration
| Retrieve the metageneration for the bucket.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: int or ``NoneType``
| :returns: The metageneration of the bucket or ``None`` if the bucket's
| resource has not been loaded from the server.
|
| object_retention_mode
| Retrieve the object retention mode set on the bucket.
|
| :rtype: str
| :returns: When set to Enabled, retention configurations can be
| set on objects in the bucket.
|
| owner
| Retrieve info about the owner of the bucket.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: dict or ``NoneType``
| :returns: Mapping of owner's role/ID. Returns ``None`` if the bucket's
| resource has not been loaded from the server.
|
| path
| The URL path to this bucket.
|
| project_number
| Retrieve the number of the project to which the bucket is assigned.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: int or ``NoneType``
| :returns: The project number that owns the bucket or ``None`` if
| the bucket's resource has not been loaded from the server.
|
| retention_policy_effective_time
| Retrieve the effective time of the bucket's retention policy.
|
| :rtype: datetime.datetime or ``NoneType``
| :returns: point-in time at which the bucket's retention policy is
| effective, or ``None`` if the property is not
| set locally.
|
| retention_policy_locked
| Retrieve whthere the bucket's retention policy is locked.
|
| :rtype: bool
| :returns: True if the bucket's policy is locked, or else False
| if the policy is not locked, or the property is not
| set locally.
|
| self_link
| Retrieve the URI for the bucket.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: str or ``NoneType``
| :returns: The self link for the bucket or ``None`` if
| the bucket's resource has not been loaded from the server.
|
| soft_delete_policy
| Retrieve the soft delete policy for this bucket.
|
| See https://cloud.google.com/storage/docs/soft-delete
|
| :rtype: :class:`SoftDeletePolicy`
| :returns: an instance for managing the bucket's soft delete policy.
|
| soft_delete_time
| If this bucket has been soft-deleted, returns the time at which it became soft-deleted.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns:
| (readonly) The time that the bucket became soft-deleted.
| Note this property is only set for soft-deleted buckets.
|
| time_created
| Retrieve the timestamp at which the bucket was created.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the bucket's resource has not been loaded
| from the server.
|
| updated
| Retrieve the timestamp at which the bucket was last updated.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the bucket's resource has not been loaded
| from the server.
|
| user_project
| Project ID to be billed for API requests made via this bucket.
|
| If unset, API requests are billed to the bucket owner.
|
| A user project is required for all operations on Requester Pays buckets.
|
| See https://cloud.google.com/storage/docs/requester-pays#requirements for details.
|
| :rtype: str
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| autoclass_enabled
| Whether Autoclass is enabled for this bucket.
|
| See https://cloud.google.com/storage/docs/using-autoclass for details.
|
| :setter: Update whether autoclass is enabled for this bucket.
| :getter: Query whether autoclass is enabled for this bucket.
|
| :rtype: bool
| :returns: True if enabled, else False.
|
| autoclass_terminal_storage_class
| The storage class that objects in an Autoclass bucket eventually transition to if
| they are not read for a certain length of time. Valid values are NEARLINE and ARCHIVE.
|
| See https://cloud.google.com/storage/docs/using-autoclass for details.
|
| :setter: Set the terminal storage class for Autoclass configuration.
| :getter: Get the terminal storage class for Autoclass configuration.
|
| :rtype: str
| :returns: The terminal storage class if Autoclass is enabled, else ``None``.
|
| cors
| Retrieve or set CORS policies configured for this bucket.
|
| See http://www.w3.org/TR/cors/ and
| https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| .. note::
|
| The getter for this property returns a list which contains
| *copies* of the bucket's CORS policy mappings. Mutating the list
| or one of its dicts has no effect unless you then re-assign the
| dict via the setter. E.g.:
|
| >>> policies = bucket.cors
| >>> policies.append({'origin': '/foo', ...})
| >>> policies[1]['maxAgeSeconds'] = 3600
| >>> del policies[0]
| >>> bucket.cors = policies
| >>> bucket.update()
|
| :setter: Set CORS policies for this bucket.
| :getter: Gets the CORS policies for this bucket.
|
| :rtype: list of dictionaries
| :returns: A sequence of mappings describing each CORS policy.
|
| default_event_based_hold
| Scalar property getter.
|
| default_kms_key_name
| Retrieve / set default KMS encryption key for objects in the bucket.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :setter: Set default KMS encryption key for items in this bucket.
| :getter: Get default KMS encryption key for items in this bucket.
|
| :rtype: str
| :returns: Default KMS encryption key, or ``None`` if not set.
|
| encryption
| Retrieve encryption configuration for this bucket.
|
| :rtype: :class:`BucketEncryption`
| :returns: an instance for managing the bucket's encryption configuration.
|
| hierarchical_namespace_enabled
| Whether hierarchical namespace is enabled for this bucket.
|
| :setter: Update whether hierarchical namespace is enabled for this bucket.
| :getter: Query whether hierarchical namespace is enabled for this bucket.
|
| :rtype: bool
| :returns: True if enabled, else False.
|
| ip_filter
| Retrieve or set the IP Filter configuration for this bucket.
|
| See https://cloud.google.com/storage/docs/ip-filtering-overview and
| https://cloud.google.com/storage/docs/json_api/v1/buckets#ipFilter
|
| .. note::
| The getter for this property returns an
| :class:`~google.cloud.storage.ip_filter.IPFilter` object, which is a
| structured representation of the bucket's IP filter configuration.
| Modifying the returned object has no effect. To update the bucket's
| IP filter, create and assign a new ``IPFilter`` object to this
| property and then call
| :meth:`~google.cloud.storage.bucket.Bucket.patch`.
|
| .. code-block:: python
|
| from google.cloud.storage.ip_filter import (
| IPFilter,
| PublicNetworkSource,
| )
|
| ip_filter = IPFilter()
| ip_filter.mode = "Enabled"
| ip_filter.public_network_source = PublicNetworkSource(
| allowed_ip_cidr_ranges=["203.0.113.5/32"]
| )
| bucket.ip_filter = ip_filter
| bucket.patch()
|
| :setter: Set the IP Filter configuration for this bucket.
| :getter: Gets the IP Filter configuration for this bucket.
|
| :rtype: :class:`~google.cloud.storage.ip_filter.IPFilter` or ``NoneType``
| :returns:
| An ``IPFilter`` object representing the configuration, or ``None``
| if no filter is configured.
|
| labels
| Retrieve or set labels assigned to this bucket.
|
| See
| https://cloud.google.com/storage/docs/json_api/v1/buckets#labels
|
| .. note::
|
| The getter for this property returns a dict which is a *copy*
| of the bucket's labels. Mutating that dict has no effect unless
| you then re-assign the dict via the setter. E.g.:
|
| >>> labels = bucket.labels
| >>> labels['new_key'] = 'some-label'
| >>> del labels['old_key']
| >>> bucket.labels = labels
| >>> bucket.update()
|
| :setter: Set labels for this bucket.
| :getter: Gets the labels for this bucket.
|
| :rtype: :class:`dict`
| :returns: Name-value pairs (string->string) labelling the bucket.
|
| lifecycle_rules
| Retrieve or set lifecycle rules configured for this bucket.
|
| See https://cloud.google.com/storage/docs/lifecycle and
| https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| .. note::
|
| The getter for this property returns a generator which yields
| *copies* of the bucket's lifecycle rules mappings. Mutating the
| output dicts has no effect unless you then re-assign the dict via
| the setter. E.g.:
|
| >>> rules = list(bucket.lifecycle_rules)
| >>> rules.append({'origin': '/foo', ...})
| >>> rules[1]['rule']['action']['type'] = 'Delete'
| >>> del rules[0]
| >>> bucket.lifecycle_rules = rules
| >>> bucket.update()
|
| :setter: Set lifecycle rules for this bucket.
| :getter: Gets the lifecycle rules for this bucket.
|
| :rtype: generator(dict)
| :returns: A sequence of mappings describing each lifecycle rule.
|
| location
| Retrieve location configured for this bucket.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets and
| https://cloud.google.com/storage/docs/locations
|
| Returns ``None`` if the property has not been set before creation,
| or if the bucket's resource has not been loaded from the server.
| :rtype: str or ``NoneType``
|
| requester_pays
| Does the requester pay for API requests for this bucket?
|
| See https://cloud.google.com/storage/docs/requester-pays for
| details.
|
| :setter: Update whether requester pays for this bucket.
| :getter: Query whether requester pays for this bucket.
|
| :rtype: bool
| :returns: True if requester pays for API requests for the bucket,
| else False.
|
| retention_period
| Retrieve or set the retention period for items in the bucket.
|
| :rtype: int or ``NoneType``
| :returns: number of seconds to retain items after upload or release
| from event-based lock, or ``None`` if the property is not
| set locally.
|
| rpo
| Get the RPO (Recovery Point Objective) of this bucket
|
| See: https://cloud.google.com/storage/docs/managing-turbo-replication
|
| "ASYNC_TURBO" or "DEFAULT"
| :rtype: str
|
| storage_class
| Retrieve or set the storage class for the bucket.
|
| See https://cloud.google.com/storage/docs/storage-classes
|
| :setter: Set the storage class for this bucket.
| :getter: Gets the the storage class for this bucket.
|
| :rtype: str or ``NoneType``
| :returns:
| If set, one of
| :attr:`~google.cloud.storage.constants.NEARLINE_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.COLDLINE_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.ARCHIVE_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.STANDARD_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.MULTI_REGIONAL_LEGACY_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.REGIONAL_LEGACY_STORAGE_CLASS`,
| or
| :attr:`~google.cloud.storage.constants.DURABLE_REDUCED_AVAILABILITY_LEGACY_STORAGE_CLASS`,
| else ``None``.
|
| versioning_enabled
| Is versioning enabled for this bucket?
|
| See https://cloud.google.com/storage/docs/object-versioning for
| details.
|
| :setter: Update whether versioning is enabled for this bucket.
| :getter: Query whether versioning is enabled for this bucket.
|
| :rtype: bool
| :returns: True if enabled, else False.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| STORAGE_CLASSES = ('STANDARD', 'NEARLINE', 'COLDLINE', 'ARCHIVE', 'MUL...
|
| ----------------------------------------------------------------------
| Data descriptors inherited from google.cloud.storage._helpers._PropertyMixin:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
google-cloud-storage.Client
Python Library Documentation: class Client in module google.cloud.storage.client
class Client(google.cloud.client.ClientWithProject)
| Client(project=<object object at 0x0000022E2C0196D0>, credentials=None, _http=None, client_info=None, client_options=None, use_auth_w_custom_endpoint=True, extra_headers={}, *, api_key=None)
|
| Client to bundle configuration needed for API requests.
|
| :type project: str or None
| :param project: 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.
|
| :type credentials: :class:`~google.auth.credentials.Credentials`
| :param 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.
|
| :type _http: :class:`~requests.Session`
| :param _http: (Optional) HTTP object to make requests. Can be any object
| that defines ``request()`` with the same interface as
| :meth:`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.
|
| :type client_info: :class:`~google.api_core.client_info.ClientInfo`
| :param client_info:
| 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.
|
| :type client_options: :class:`~google.api_core.client_options.ClientOptions` or :class:`dict`
| :param client_options: (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.
|
| :type use_auth_w_custom_endpoint: bool
| :param use_auth_w_custom_endpoint:
| (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.
|
| :type extra_headers: dict
| :param extra_headers:
| (Optional) Custom headers to be sent with the requests attached to the client.
| For example, you can add custom audit logging headers.
|
| :type api_key: string
| :param api_key:
| (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.
|
| Method resolution order:
| Client
| google.cloud.client.ClientWithProject
| google.cloud.client.Client
| google.cloud.client._ClientFactoryMixin
| google.cloud.client._ClientProjectMixin
| builtins.object
|
| Methods defined here:
|
| __enter__(self)
|
| __exit__(self, exc_type, exc_val, exc_tb)
|
| __init__(self, project=<object object at 0x0000022E2C0196D0>, credentials=None, _http=None, client_info=None, client_options=None, use_auth_w_custom_endpoint=True, extra_headers={}, *, api_key=None)
| Initialize self. See help(type(self)) for accurate signature.
|
| batch(self, raise_exception=True)
| Factory constructor for batch object.
|
| .. note::
| This will not make an HTTP request; it simply instantiates
| a batch object owned by this client.
|
| :type raise_exception: bool
| :param raise_exception:
| (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.
|
| :rtype: :class:`google.cloud.storage.batch.Batch`
| :returns: The batch object created.
|
| bucket(self, bucket_name, user_project=None, generation=None)
| Factory constructor for bucket object.
|
| .. note::
| This will not make an HTTP request; it simply instantiates
| a bucket object owned by this client.
|
| :type bucket_name: str
| :param bucket_name: The name of the bucket to be instantiated.
|
| :type user_project: str
| :param user_project: (Optional) The project ID to be billed for API
| requests made via the bucket.
|
| :type generation: int
| :param generation: (Optional) If present, selects a specific revision of
| this bucket.
|
| :rtype: :class:`google.cloud.storage.bucket.Bucket`
| :returns: The bucket object created.
|
| close(self)
| Close the client and clear any cached metadata or active connections.
|
| create_bucket(self, bucket_or_name, requester_pays=None, project=None, user_project=None, location=None, data_locations=None, predefined_acl=None, predefined_default_object_acl=None, enable_object_retention=False, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Create a new bucket via a POST request.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/buckets/insert) and a [code sample](https://cloud.google.com/storage/docs/samples/storage-create-bucket#storage_create_bucket-python).
|
| Args:
| bucket_or_name (Union[ :class:`~google.cloud.storage.bucket.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 :meth:`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.
|
| Returns:
| google.cloud.storage.bucket.Bucket
| The newly created bucket.
|
| Raises:
| google.cloud.exceptions.Conflict
| If the bucket already exists.
|
| create_hmac_key(self, service_account_email, project_id=None, user_project=None, timeout=60, retry=None)
| Create an HMAC key for a service account.
|
| :type service_account_email: str
| :param service_account_email: e-mail address of the service account
|
| :type project_id: str
| :param project_id: (Optional) Explicit project ID for the key.
| Defaults to the client's project.
|
| :type user_project: str
| :param user_project: (Optional) This parameter is currently ignored.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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.
|
| :rtype:
| Tuple[:class:`~google.cloud.storage.hmac_key.HMACKeyMetadata`, str]
| :returns: metadata for the created key, plus the bytes of the key's secret, which is an 40-character base64-encoded string.
|
| download_blob_to_file(self, blob_or_uri, file_obj, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='auto', retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, single_shot_download=False)
| Download the contents of a blob object or blob URI into a file-like object.
|
| See https://cloud.google.com/storage/docs/downloading-objects
|
| Args:
| blob_or_uri (Union[ :class:`~google.cloud.storage.blob.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: :ref:`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.
|
| generate_signed_post_policy_v4(self, bucket_name, blob_name, expiration, conditions=None, fields=None, credentials=None, virtual_hosted_style=False, bucket_bound_hostname=None, scheme='http', service_account_email=None, access_token=None)
| Generate a V4 signed policy object. Generated policy object allows user to upload objects with a POST request.
|
| .. note::
|
| Assumes ``credentials`` implements the
| :class:`google.auth.credentials.Signing` interface. Also assumes
| ``credentials`` has a ``service_account_email`` property which
| identifies the credentials.
|
| See a [code sample](https://github.com/googleapis/python-storage/blob/main/samples/snippets/storage_generate_signed_post_policy_v4.py).
|
| :type bucket_name: str
| :param bucket_name: Bucket name.
|
| :type blob_name: str
| :param blob_name: Object name.
|
| :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
| :param expiration: Policy expiration time. If a ``datetime`` instance is
| passed without an explicit ``tzinfo`` set, it will be
| assumed to be ``UTC``.
|
| :type conditions: list
| :param conditions: (Optional) List of POST policy conditions, which are
| used to restrict what is allowed in the request.
|
| :type fields: dict
| :param fields: (Optional) Additional elements to include into request.
|
| :type credentials: :class:`google.auth.credentials.Signing`
| :param credentials: (Optional) Credentials object with an associated private
| key to sign text.
|
| :type virtual_hosted_style: bool
| :param virtual_hosted_style:
| (Optional) If True, construct the URL relative to the bucket
| virtual hostname, e.g., '<bucket-name>.storage.googleapis.com'.
| Incompatible with bucket_bound_hostname.
|
| :type bucket_bound_hostname: str
| :param bucket_bound_hostname:
| (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
|
| :type scheme: str
| :param scheme:
| (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"``.
|
| :type service_account_email: str
| :param service_account_email: (Optional) E-mail address of the service account.
|
| :type access_token: str
| :param access_token: (Optional) Access token for a service account.
|
| :raises: :exc:`ValueError` when mutually exclusive arguments are used.
|
| :rtype: dict
| :returns: Signed POST policy.
|
| get_bucket(self, bucket_or_name, timeout=60, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, *, generation=None, soft_deleted=None)
| Retrieve a bucket via a GET request.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/buckets/get) and a [code sample](https://cloud.google.com/storage/docs/samples/storage-get-bucket-metadata#storage_get_bucket_metadata-python).
|
| Args:
| bucket_or_name (Union[ :class:`~google.cloud.storage.bucket.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 :meth:`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
|
| Returns:
| google.cloud.storage.bucket.Bucket
| The bucket matching the name provided.
|
| Raises:
| google.cloud.exceptions.NotFound
| If the bucket is not found.
|
| get_hmac_key_metadata(self, access_id, project_id=None, user_project=None, timeout=60)
| Return a metadata instance for the given HMAC key.
|
| :type access_id: str
| :param access_id: Unique ID of an existing key.
|
| :type project_id: str
| :param project_id: (Optional) Project ID of an existing key.
| Defaults to client's project.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type user_project: str
| :param user_project: (Optional) This parameter is currently ignored.
|
| get_service_account_email(self, project=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Get the email address of the project's GCS service account
|
| :type project: str
| :param project:
| (Optional) Project ID to use for retreiving GCS service account
| email address. Defaults to the client's project.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: str
| :returns: service account email address
|
| list_blobs(self, bucket_or_name, max_results=None, page_token=None, prefix=None, delimiter=None, start_offset=None, end_offset=None, include_trailing_delimiter=None, versions=None, projection='noAcl', fields=None, page_size=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, match_glob=None, include_folders_as_prefixes=None, soft_deleted=None, filter_=None)
| Return an iterator used to find blobs in the bucket.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| .. note::
| List prefixes (directories) in a bucket using a prefix and delimiter.
| See a [code sample](https://cloud.google.com/storage/docs/samples/storage-list-files-with-prefix#storage_list_files_with_prefix-python)
| listing objects using a prefix filter.
|
| Args:
| bucket_or_name (Union[ :class:`~google.cloud.storage.bucket.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 :meth:`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
|
| filter_ (str):
| (Optional) Filter string used to filter objects. See:
| https://docs.cloud.google.com/storage/docs/listing-objects#filter-by-object-contexts-syntax
|
| Returns:
| Iterator of all :class:`~google.cloud.storage.blob.Blob`
| in this bucket matching the arguments. The RPC call
| returns a response when the iterator is consumed.
|
| As part of the response, you'll also get back an iterator.prefixes entity that lists object names
| up to and including the requested delimiter. Duplicate entries are omitted from this list.
|
| list_buckets(self, max_results=None, page_token=None, prefix=None, projection='noAcl', fields=None, project=None, page_size=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, *, soft_deleted=None, return_partial_success=None)
| Get all buckets in the project associated to the client.
|
| This will not populate the list of blobs available in each
| bucket.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/buckets/list) and a [code sample](https://cloud.google.com/storage/docs/samples/storage-list-buckets#storage_list_buckets-python).
|
| :type max_results: int
| :param max_results: (Optional) The maximum number of buckets to return.
|
| :type page_token: str
| :param page_token:
| (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.
|
| :type prefix: str
| :param prefix: (Optional) Filter results to buckets whose names begin
| with this prefix.
|
| :type projection: str
| :param projection:
| (Optional) Specifies the set of properties to return. If used, must
| be 'full' or 'noAcl'. Defaults to 'noAcl'.
|
| :type fields: str
| :param fields:
| (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'
|
| :type project: str
| :param project: (Optional) The project whose buckets are to be listed.
| If not passed, uses the project set on the client.
|
| :type page_size: int
| :param page_size: (Optional) Maximum number of buckets to return in each page.
| Defaults to a value set by the API.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type soft_deleted: bool
| :param soft_deleted:
| (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 return_partial_success: bool
| :param return_partial_success:
| (Optional) If True, the response will also contain a list of
| unreachable buckets if the buckets are unavailable. The
| unreachable buckets will be available on the ``unreachable``
| attribute of the returned iterator.
|
| :rtype: :class:`~google.api_core.page_iterator.Iterator`
| :raises ValueError: if both ``project`` is ``None`` and the client's
| project is also ``None``.
| :returns: Iterator of all :class:`~google.cloud.storage.bucket.Bucket`
| belonging to this project.
|
| list_hmac_keys(self, max_results=None, service_account_email=None, show_deleted_keys=None, project_id=None, user_project=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| List HMAC keys for a project.
|
| :type max_results: int
| :param max_results:
| (Optional) Max number of keys to return in a given page.
|
| :type service_account_email: str
| :param service_account_email:
| (Optional) Limit keys to those created by the given service account.
|
| :type show_deleted_keys: bool
| :param show_deleted_keys:
| (Optional) Included deleted keys in the list. Default is to
| exclude them.
|
| :type project_id: str
| :param project_id: (Optional) Explicit project ID for the key.
| Defaults to the client's project.
|
| :type user_project: str
| :param user_project: (Optional) This parameter is currently ignored.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype:
| Tuple[:class:`~google.cloud.storage.hmac_key.HMACKeyMetadata`, str]
| :returns: metadata for the created key, plus the bytes of the key's secret, which is an 40-character base64-encoded string.
|
| lookup_bucket(self, bucket_name, timeout=60, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| 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 a NotFound exception.
|
| :type bucket_name: str
| :param bucket_name: The name of the bucket to get.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration matches the given value.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration does not match the given value.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: :class:`google.cloud.storage.bucket.Bucket` or ``NoneType``
| :returns: The bucket matching the name provided or None if not found.
|
| restore_bucket(self, bucket_name, generation, projection='noAcl', if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Restores a soft-deleted bucket.
|
| :type bucket_name: str
| :param bucket_name: The name of the bucket to be restored.
|
| :type generation: int
| :param generation: Selects the specific revision of the bucket.
|
| :type projection: str
| :param projection:
| (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.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC.
|
| Users can configure non-default retry behavior. A ``None`` value will
| disable retries. See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| :rtype: :class:`google.cloud.storage.bucket.Bucket`
| :returns: The restored Bucket.
|
| update_user_agent(self, user_agent)
| Update the user-agent string for this client.
|
| :type user_agent: str
| :param user_agent: The string to add to the user-agent.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| create_anonymous_client()
| Factory: return client with anonymous credentials.
|
| .. note::
|
| Such a client has only limited access to "public" buckets:
| listing their contents and downloading their blobs.
|
| :rtype: :class:`google.cloud.storage.client.Client`
| :returns: Instance w/ anonymous credentials and no project.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| api_endpoint
|
| current_batch
| Currently-active batch.
|
| :rtype: :class:`google.cloud.storage.batch.Batch` or ``NoneType`` (if
| no batch is active).
| :returns: The batch at the top of the batch stack.
|
| universe_domain
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| SCOPE = ('https://www.googleapis.com/auth/devstorage.full_control', 'h...
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from google.cloud.client.Client:
|
| __getstate__(self)
| Explicitly state that clients are not pickleable.
|
| ----------------------------------------------------------------------
| Class methods inherited from google.cloud.client._ClientFactoryMixin:
|
| from_service_account_info(info, *args, **kwargs)
| Factory to retrieve JSON credentials while creating client.
|
| :type info: dict
| :param info:
| The JSON object with a private key and other credentials
| information (downloaded from the Google APIs console).
|
| :type args: tuple
| :param args: Remaining positional arguments to pass to constructor.
|
| :param kwargs: Remaining keyword arguments to pass to constructor.
|
| :rtype: :class:`_ClientFactoryMixin`
| :returns: The client created with the retrieved JSON credentials.
| :raises TypeError: if there is a conflict with the kwargs
| and the credentials created by the factory.
|
| from_service_account_json(json_credentials_path, *args, **kwargs)
| Factory to retrieve JSON credentials while creating client.
|
| :type json_credentials_path: str
| :param json_credentials_path: The path to a private key file (this file
| was given to you when you created the
| service account). This file must contain
| a JSON object with a private key and
| other credentials information (downloaded
| from the Google APIs console).
|
| :type args: tuple
| :param args: Remaining positional arguments to pass to constructor.
|
| :param kwargs: Remaining keyword arguments to pass to constructor.
|
| :rtype: :class:`_ClientFactoryMixin`
| :returns: The client created with the retrieved JSON credentials.
| :raises TypeError: if there is a conflict with the kwargs
| and the credentials created by the factory.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from google.cloud.client._ClientFactoryMixin:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
google-cloud-storage.acl
Python Library Documentation: module google.cloud.storage.acl in google.cloud.storage
NAME
google.cloud.storage.acl - Manage access to objects and buckets.
CLASSES
builtins.object
ACL
BucketACL
DefaultObjectACL
ObjectACL
class ACL(builtins.object)
| Container class representing a list of access controls.
|
| Methods defined here:
|
| __init__(self)
| Initialize self. See help(type(self)) for accurate signature.
|
| __iter__(self)
|
| add_entity(self, entity)
| Add an entity to the ACL.
|
| :type entity: :class:`_ACLEntity`
| :param entity: The entity to add to this ACL.
|
| all(self)
| Factory method for an Entity representing all users.
|
| :rtype: :class:`_ACLEntity`
| :returns: An entity representing all users.
|
| all_authenticated(self)
| Factory method for an Entity representing all authenticated users.
|
| :rtype: :class:`_ACLEntity`
| :returns: An entity representing all authenticated users.
|
| clear(self, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Remove all ACL entries.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| Note that this won't actually remove *ALL* the rules, but it
| will remove all the non-default rules. In short, you'll still
| have access to a bucket that you created even after you clear
| ACL rules with this method.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| domain(self, domain)
| Factory method for a domain Entity.
|
| :type domain: str
| :param domain: The domain for this entity.
|
| :rtype: :class:`_ACLEntity`
| :returns: An entity corresponding to this domain.
|
| entity(self, entity_type, identifier=None)
| Factory method for creating an Entity.
|
| If an entity with the same type and identifier already exists,
| this will return a reference to that entity. If not, it will
| create a new one and add it to the list of known entities for
| this ACL.
|
| :type entity_type: str
| :param entity_type: The type of entity to create
| (ie, ``user``, ``group``, etc)
|
| :type identifier: str
| :param identifier: The ID of the entity (if applicable).
| This can be either an ID or an e-mail address.
|
| :rtype: :class:`_ACLEntity`
| :returns: A new Entity or a reference to an existing identical entity.
|
| entity_from_dict(self, entity_dict)
| Build an _ACLEntity object from a dictionary of data.
|
| An entity is a mutable object that represents a list of roles
| belonging to either a user or group or the special types for all
| users and all authenticated users.
|
| :type entity_dict: dict
| :param entity_dict: Dictionary full of data from an ACL lookup.
|
| :rtype: :class:`_ACLEntity`
| :returns: An Entity constructed from the dictionary.
|
| get_entities(self)
| Get a list of all Entity objects.
|
| :rtype: list of :class:`_ACLEntity` objects
| :returns: A list of all Entity objects.
|
| get_entity(self, entity, default=None)
| Gets an entity object from the ACL.
|
| :type entity: :class:`_ACLEntity` or string
| :param entity: The entity to get lookup in the ACL.
|
| :type default: anything
| :param default: This value will be returned if the entity
| doesn't exist.
|
| :rtype: :class:`_ACLEntity`
| :returns: The corresponding entity or the value provided
| to ``default``.
|
| group(self, identifier)
| Factory method for a group Entity.
|
| :type identifier: str
| :param identifier: An id or e-mail for this particular group.
|
| :rtype: :class:`_ACLEntity`
| :returns: An Entity corresponding to this group.
|
| has_entity(self, entity)
| Returns whether or not this ACL has any entries for an entity.
|
| :type entity: :class:`_ACLEntity`
| :param entity: The entity to check for existence in this ACL.
|
| :rtype: bool
| :returns: True of the entity exists in the ACL.
|
| reload(self, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Reload the ACL data from Cloud Storage.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: :class:`~google.api_core.retry.Retry`
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| reset(self)
| Remove all entities from the ACL, and clear the ``loaded`` flag.
|
| save(self, acl=None, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Save this ACL for the current bucket.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type acl: :class:`google.cloud.storage.acl.ACL`, or a compatible list.
| :param acl: The ACL object to save. If left blank, this will save
| current entries.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| save_predefined(self, predefined, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Save this ACL for the current bucket using a predefined ACL.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type predefined: str
| :param predefined: An identifier for a predefined ACL. Must be one
| of the keys in :attr:`PREDEFINED_JSON_ACLS`
| or :attr:`PREDEFINED_XML_ACLS` (which will be
| aliased to the corresponding JSON name).
| If passed, `acl` must be None.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| user(self, identifier)
| Factory method for a user Entity.
|
| :type identifier: str
| :param identifier: An id or e-mail for this particular user.
|
| :rtype: :class:`_ACLEntity`
| :returns: An Entity corresponding to this user.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| validate_predefined(predefined)
| Ensures predefined is in list of predefined json values
|
| :type predefined: str
| :param predefined: name of a predefined acl
|
| :type predefined: str
| :param predefined: validated JSON name of predefined acl
|
| :raises: :exc: `ValueError`: If predefined is not a valid acl
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| client
| Abstract getter for the object client.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| PREDEFINED_JSON_ACLS = frozenset({'authenticatedRead', 'bucketOwnerFul...
|
| PREDEFINED_XML_ACLS = {'authenticated-read': 'authenticatedRead', 'buc...
|
| loaded = False
|
| reload_path = None
|
| save_path = None
|
| user_project = None
class BucketACL(ACL)
| BucketACL(bucket)
|
| An ACL specifically for a bucket.
|
| :type bucket: :class:`google.cloud.storage.bucket.Bucket`
| :param bucket: The bucket to which this ACL relates.
|
| Method resolution order:
| BucketACL
| ACL
| builtins.object
|
| Methods defined here:
|
| __init__(self, bucket)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| client
| The client bound to this ACL's bucket.
|
| reload_path
| Compute the path for GET API requests for this ACL.
|
| save_path
| Compute the path for PATCH API requests for this ACL.
|
| user_project
| Compute the user project charged for API requests for this ACL.
|
| ----------------------------------------------------------------------
| Methods inherited from ACL:
|
| __iter__(self)
|
| add_entity(self, entity)
| Add an entity to the ACL.
|
| :type entity: :class:`_ACLEntity`
| :param entity: The entity to add to this ACL.
|
| all(self)
| Factory method for an Entity representing all users.
|
| :rtype: :class:`_ACLEntity`
| :returns: An entity representing all users.
|
| all_authenticated(self)
| Factory method for an Entity representing all authenticated users.
|
| :rtype: :class:`_ACLEntity`
| :returns: An entity representing all authenticated users.
|
| clear(self, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Remove all ACL entries.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| Note that this won't actually remove *ALL* the rules, but it
| will remove all the non-default rules. In short, you'll still
| have access to a bucket that you created even after you clear
| ACL rules with this method.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| domain(self, domain)
| Factory method for a domain Entity.
|
| :type domain: str
| :param domain: The domain for this entity.
|
| :rtype: :class:`_ACLEntity`
| :returns: An entity corresponding to this domain.
|
| entity(self, entity_type, identifier=None)
| Factory method for creating an Entity.
|
| If an entity with the same type and identifier already exists,
| this will return a reference to that entity. If not, it will
| create a new one and add it to the list of known entities for
| this ACL.
|
| :type entity_type: str
| :param entity_type: The type of entity to create
| (ie, ``user``, ``group``, etc)
|
| :type identifier: str
| :param identifier: The ID of the entity (if applicable).
| This can be either an ID or an e-mail address.
|
| :rtype: :class:`_ACLEntity`
| :returns: A new Entity or a reference to an existing identical entity.
|
| entity_from_dict(self, entity_dict)
| Build an _ACLEntity object from a dictionary of data.
|
| An entity is a mutable object that represents a list of roles
| belonging to either a user or group or the special types for all
| users and all authenticated users.
|
| :type entity_dict: dict
| :param entity_dict: Dictionary full of data from an ACL lookup.
|
| :rtype: :class:`_ACLEntity`
| :returns: An Entity constructed from the dictionary.
|
| get_entities(self)
| Get a list of all Entity objects.
|
| :rtype: list of :class:`_ACLEntity` objects
| :returns: A list of all Entity objects.
|
| get_entity(self, entity, default=None)
| Gets an entity object from the ACL.
|
| :type entity: :class:`_ACLEntity` or string
| :param entity: The entity to get lookup in the ACL.
|
| :type default: anything
| :param default: This value will be returned if the entity
| doesn't exist.
|
| :rtype: :class:`_ACLEntity`
| :returns: The corresponding entity or the value provided
| to ``default``.
|
| group(self, identifier)
| Factory method for a group Entity.
|
| :type identifier: str
| :param identifier: An id or e-mail for this particular group.
|
| :rtype: :class:`_ACLEntity`
| :returns: An Entity corresponding to this group.
|
| has_entity(self, entity)
| Returns whether or not this ACL has any entries for an entity.
|
| :type entity: :class:`_ACLEntity`
| :param entity: The entity to check for existence in this ACL.
|
| :rtype: bool
| :returns: True of the entity exists in the ACL.
|
| reload(self, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Reload the ACL data from Cloud Storage.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: :class:`~google.api_core.retry.Retry`
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| reset(self)
| Remove all entities from the ACL, and clear the ``loaded`` flag.
|
| save(self, acl=None, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Save this ACL for the current bucket.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type acl: :class:`google.cloud.storage.acl.ACL`, or a compatible list.
| :param acl: The ACL object to save. If left blank, this will save
| current entries.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| save_predefined(self, predefined, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Save this ACL for the current bucket using a predefined ACL.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type predefined: str
| :param predefined: An identifier for a predefined ACL. Must be one
| of the keys in :attr:`PREDEFINED_JSON_ACLS`
| or :attr:`PREDEFINED_XML_ACLS` (which will be
| aliased to the corresponding JSON name).
| If passed, `acl` must be None.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| user(self, identifier)
| Factory method for a user Entity.
|
| :type identifier: str
| :param identifier: An id or e-mail for this particular user.
|
| :rtype: :class:`_ACLEntity`
| :returns: An Entity corresponding to this user.
|
| ----------------------------------------------------------------------
| Class methods inherited from ACL:
|
| validate_predefined(predefined)
| Ensures predefined is in list of predefined json values
|
| :type predefined: str
| :param predefined: name of a predefined acl
|
| :type predefined: str
| :param predefined: validated JSON name of predefined acl
|
| :raises: :exc: `ValueError`: If predefined is not a valid acl
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ACL:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ACL:
|
| PREDEFINED_JSON_ACLS = frozenset({'authenticatedRead', 'bucketOwnerFul...
|
| PREDEFINED_XML_ACLS = {'authenticated-read': 'authenticatedRead', 'buc...
|
| loaded = False
class DefaultObjectACL(BucketACL)
| DefaultObjectACL(bucket)
|
| A class representing the default object ACL for a bucket.
|
| Method resolution order:
| DefaultObjectACL
| BucketACL
| ACL
| builtins.object
|
| Methods inherited from BucketACL:
|
| __init__(self, bucket)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from BucketACL:
|
| client
| The client bound to this ACL's bucket.
|
| reload_path
| Compute the path for GET API requests for this ACL.
|
| save_path
| Compute the path for PATCH API requests for this ACL.
|
| user_project
| Compute the user project charged for API requests for this ACL.
|
| ----------------------------------------------------------------------
| Methods inherited from ACL:
|
| __iter__(self)
|
| add_entity(self, entity)
| Add an entity to the ACL.
|
| :type entity: :class:`_ACLEntity`
| :param entity: The entity to add to this ACL.
|
| all(self)
| Factory method for an Entity representing all users.
|
| :rtype: :class:`_ACLEntity`
| :returns: An entity representing all users.
|
| all_authenticated(self)
| Factory method for an Entity representing all authenticated users.
|
| :rtype: :class:`_ACLEntity`
| :returns: An entity representing all authenticated users.
|
| clear(self, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Remove all ACL entries.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| Note that this won't actually remove *ALL* the rules, but it
| will remove all the non-default rules. In short, you'll still
| have access to a bucket that you created even after you clear
| ACL rules with this method.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| domain(self, domain)
| Factory method for a domain Entity.
|
| :type domain: str
| :param domain: The domain for this entity.
|
| :rtype: :class:`_ACLEntity`
| :returns: An entity corresponding to this domain.
|
| entity(self, entity_type, identifier=None)
| Factory method for creating an Entity.
|
| If an entity with the same type and identifier already exists,
| this will return a reference to that entity. If not, it will
| create a new one and add it to the list of known entities for
| this ACL.
|
| :type entity_type: str
| :param entity_type: The type of entity to create
| (ie, ``user``, ``group``, etc)
|
| :type identifier: str
| :param identifier: The ID of the entity (if applicable).
| This can be either an ID or an e-mail address.
|
| :rtype: :class:`_ACLEntity`
| :returns: A new Entity or a reference to an existing identical entity.
|
| entity_from_dict(self, entity_dict)
| Build an _ACLEntity object from a dictionary of data.
|
| An entity is a mutable object that represents a list of roles
| belonging to either a user or group or the special types for all
| users and all authenticated users.
|
| :type entity_dict: dict
| :param entity_dict: Dictionary full of data from an ACL lookup.
|
| :rtype: :class:`_ACLEntity`
| :returns: An Entity constructed from the dictionary.
|
| get_entities(self)
| Get a list of all Entity objects.
|
| :rtype: list of :class:`_ACLEntity` objects
| :returns: A list of all Entity objects.
|
| get_entity(self, entity, default=None)
| Gets an entity object from the ACL.
|
| :type entity: :class:`_ACLEntity` or string
| :param entity: The entity to get lookup in the ACL.
|
| :type default: anything
| :param default: This value will be returned if the entity
| doesn't exist.
|
| :rtype: :class:`_ACLEntity`
| :returns: The corresponding entity or the value provided
| to ``default``.
|
| group(self, identifier)
| Factory method for a group Entity.
|
| :type identifier: str
| :param identifier: An id or e-mail for this particular group.
|
| :rtype: :class:`_ACLEntity`
| :returns: An Entity corresponding to this group.
|
| has_entity(self, entity)
| Returns whether or not this ACL has any entries for an entity.
|
| :type entity: :class:`_ACLEntity`
| :param entity: The entity to check for existence in this ACL.
|
| :rtype: bool
| :returns: True of the entity exists in the ACL.
|
| reload(self, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Reload the ACL data from Cloud Storage.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: :class:`~google.api_core.retry.Retry`
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| reset(self)
| Remove all entities from the ACL, and clear the ``loaded`` flag.
|
| save(self, acl=None, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Save this ACL for the current bucket.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type acl: :class:`google.cloud.storage.acl.ACL`, or a compatible list.
| :param acl: The ACL object to save. If left blank, this will save
| current entries.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| save_predefined(self, predefined, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Save this ACL for the current bucket using a predefined ACL.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type predefined: str
| :param predefined: An identifier for a predefined ACL. Must be one
| of the keys in :attr:`PREDEFINED_JSON_ACLS`
| or :attr:`PREDEFINED_XML_ACLS` (which will be
| aliased to the corresponding JSON name).
| If passed, `acl` must be None.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| user(self, identifier)
| Factory method for a user Entity.
|
| :type identifier: str
| :param identifier: An id or e-mail for this particular user.
|
| :rtype: :class:`_ACLEntity`
| :returns: An Entity corresponding to this user.
|
| ----------------------------------------------------------------------
| Class methods inherited from ACL:
|
| validate_predefined(predefined)
| Ensures predefined is in list of predefined json values
|
| :type predefined: str
| :param predefined: name of a predefined acl
|
| :type predefined: str
| :param predefined: validated JSON name of predefined acl
|
| :raises: :exc: `ValueError`: If predefined is not a valid acl
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ACL:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ACL:
|
| PREDEFINED_JSON_ACLS = frozenset({'authenticatedRead', 'bucketOwnerFul...
|
| PREDEFINED_XML_ACLS = {'authenticated-read': 'authenticatedRead', 'buc...
|
| loaded = False
class ObjectACL(ACL)
| ObjectACL(blob)
|
| An ACL specifically for a Cloud Storage object / blob.
|
| :type blob: :class:`google.cloud.storage.blob.Blob`
| :param blob: The blob that this ACL corresponds to.
|
| Method resolution order:
| ObjectACL
| ACL
| builtins.object
|
| Methods defined here:
|
| __init__(self, blob)
| Initialize self. See help(type(self)) for accurate signature.
|
| clear(self, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Remove all ACL entries.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| Note that this won't actually remove *ALL* the rules, but it
| will remove all the non-default rules. In short, you'll still
| have access to a bucket that you created even after you clear
| ACL rules with this method.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| save(self, acl=None, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Save this ACL for the current object.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type acl: :class:`google.cloud.storage.acl.ACL`, or a compatible list.
| :param acl: The ACL object to save. If left blank, this will save
| current entries.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| save_predefined(self, predefined, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Save this ACL for the current object using a predefined ACL.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type predefined: str
| :param predefined: An identifier for a predefined ACL. Must be one
| of the keys in :attr:`PREDEFINED_JSON_ACLS`
| or :attr:`PREDEFINED_XML_ACLS` (which will be
| aliased to the corresponding JSON name).
| If passed, `acl` must be None.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| client
| The client bound to this ACL's blob.
|
| reload_path
| Compute the path for GET API requests for this ACL.
|
| save_path
| Compute the path for PATCH API requests for this ACL.
|
| user_project
| Compute the user project charged for API requests for this ACL.
|
| ----------------------------------------------------------------------
| Methods inherited from ACL:
|
| __iter__(self)
|
| add_entity(self, entity)
| Add an entity to the ACL.
|
| :type entity: :class:`_ACLEntity`
| :param entity: The entity to add to this ACL.
|
| all(self)
| Factory method for an Entity representing all users.
|
| :rtype: :class:`_ACLEntity`
| :returns: An entity representing all users.
|
| all_authenticated(self)
| Factory method for an Entity representing all authenticated users.
|
| :rtype: :class:`_ACLEntity`
| :returns: An entity representing all authenticated users.
|
| domain(self, domain)
| Factory method for a domain Entity.
|
| :type domain: str
| :param domain: The domain for this entity.
|
| :rtype: :class:`_ACLEntity`
| :returns: An entity corresponding to this domain.
|
| entity(self, entity_type, identifier=None)
| Factory method for creating an Entity.
|
| If an entity with the same type and identifier already exists,
| this will return a reference to that entity. If not, it will
| create a new one and add it to the list of known entities for
| this ACL.
|
| :type entity_type: str
| :param entity_type: The type of entity to create
| (ie, ``user``, ``group``, etc)
|
| :type identifier: str
| :param identifier: The ID of the entity (if applicable).
| This can be either an ID or an e-mail address.
|
| :rtype: :class:`_ACLEntity`
| :returns: A new Entity or a reference to an existing identical entity.
|
| entity_from_dict(self, entity_dict)
| Build an _ACLEntity object from a dictionary of data.
|
| An entity is a mutable object that represents a list of roles
| belonging to either a user or group or the special types for all
| users and all authenticated users.
|
| :type entity_dict: dict
| :param entity_dict: Dictionary full of data from an ACL lookup.
|
| :rtype: :class:`_ACLEntity`
| :returns: An Entity constructed from the dictionary.
|
| get_entities(self)
| Get a list of all Entity objects.
|
| :rtype: list of :class:`_ACLEntity` objects
| :returns: A list of all Entity objects.
|
| get_entity(self, entity, default=None)
| Gets an entity object from the ACL.
|
| :type entity: :class:`_ACLEntity` or string
| :param entity: The entity to get lookup in the ACL.
|
| :type default: anything
| :param default: This value will be returned if the entity
| doesn't exist.
|
| :rtype: :class:`_ACLEntity`
| :returns: The corresponding entity or the value provided
| to ``default``.
|
| group(self, identifier)
| Factory method for a group Entity.
|
| :type identifier: str
| :param identifier: An id or e-mail for this particular group.
|
| :rtype: :class:`_ACLEntity`
| :returns: An Entity corresponding to this group.
|
| has_entity(self, entity)
| Returns whether or not this ACL has any entries for an entity.
|
| :type entity: :class:`_ACLEntity`
| :param entity: The entity to check for existence in this ACL.
|
| :rtype: bool
| :returns: True of the entity exists in the ACL.
|
| reload(self, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Reload the ACL data from Cloud Storage.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the ACL's parent.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: :class:`~google.api_core.retry.Retry`
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| reset(self)
| Remove all entities from the ACL, and clear the ``loaded`` flag.
|
| user(self, identifier)
| Factory method for a user Entity.
|
| :type identifier: str
| :param identifier: An id or e-mail for this particular user.
|
| :rtype: :class:`_ACLEntity`
| :returns: An Entity corresponding to this user.
|
| ----------------------------------------------------------------------
| Class methods inherited from ACL:
|
| validate_predefined(predefined)
| Ensures predefined is in list of predefined json values
|
| :type predefined: str
| :param predefined: name of a predefined acl
|
| :type predefined: str
| :param predefined: validated JSON name of predefined acl
|
| :raises: :exc: `ValueError`: If predefined is not a valid acl
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ACL:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ACL:
|
| PREDEFINED_JSON_ACLS = frozenset({'authenticatedRead', 'bucketOwnerFul...
|
| PREDEFINED_XML_ACLS = {'authenticated-read': 'authenticatedRead', 'buc...
|
| loaded = False
DATA
DEFAULT_RETRY = <google.api_core.retry.retry_unary.Retry object>
DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED = <google.cloud.storage.retr...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\google\cloud\storage\acl.py
google-cloud-storage.batch
Python Library Documentation: module google.cloud.storage.batch in google.cloud.storage
NAME
google.cloud.storage.batch - Batch updates / deletes of storage buckets / blobs.
DESCRIPTION
A batch request is a single standard HTTP request containing multiple Cloud Storage JSON API calls.
Within this main HTTP request, there are multiple parts which each contain a nested HTTP request.
The body of each part is itself a complete HTTP request, with its own verb, URL, headers, and body.
Note that Cloud Storage does not support batch operations for uploading or downloading.
Additionally, the current batch design does not support library methods whose return values
depend on the response payload. See more details in the [Sending Batch Requests official guide](https://cloud.google.com/storage/docs/batch).
Examples of situations when you might want to use the Batch module:
``blob.patch()``
``blob.update()``
``blob.delete()``
``bucket.delete_blob()``
``bucket.patch()``
``bucket.update()``
CLASSES
email.mime.application.MIMEApplication(email.mime.nonmultipart.MIMENonMultipart)
MIMEApplicationHTTP
google.cloud.storage._http.Connection(google.cloud._http.JSONConnection)
Batch
class Batch(google.cloud.storage._http.Connection)
| Batch(client, raise_exception=True)
|
| Proxy an underlying connection, batching up change operations.
|
| .. warning::
|
| Cloud Storage does not support batch operations for uploading or downloading.
| Additionally, the current batch design does not support library methods whose
| return values depend on the response payload.
|
| :type client: :class:`google.cloud.storage.client.Client`
| :param client: The client to use for making connections.
|
| :type raise_exception: bool
| :param raise_exception:
| (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.
|
| Method resolution order:
| Batch
| google.cloud.storage._http.Connection
| google.cloud._http.JSONConnection
| google.cloud._http.Connection
| builtins.object
|
| Methods defined here:
|
| __enter__(self)
|
| __exit__(self, exc_type, exc_val, exc_tb)
|
| __init__(self, client, raise_exception=True)
| Initialize self. See help(type(self)) for accurate signature.
|
| current(self)
| Return the topmost batch, or None.
|
| finish(self, raise_exception=True)
| Submit a single `multipart/mixed` request with deferred requests.
|
| :type raise_exception: bool
| :param raise_exception:
| (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.
|
| :rtype: list of tuples
| :returns: one ``(headers, payload)`` tuple per deferred request.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from google.cloud.storage._http.Connection:
|
| api_request(self, *args, **kwargs)
| Make a request over the HTTP transport to the API.
|
| You shouldn't need to use this method, but if you plan to
| interact with the API using these primitives, this is the
| correct one to use.
|
| :type method: str
| :param method: The HTTP method name (ie, ``GET``, ``POST``, etc).
| Required.
|
| :type path: str
| :param path: The path to the resource (ie, ``'/b/bucket-name'``).
| Required.
|
| :type query_params: dict or list
| :param query_params: A dictionary of keys and values (or list of
| key-value pairs) to insert into the query
| string of the URL.
|
| :type data: str
| :param data: The data to send as the body of the request. Default is
| the empty string.
|
| :type content_type: str
| :param content_type: The proper MIME type of the data provided. Default
| is None.
|
| :type headers: dict
| :param headers: extra HTTP headers to be sent with the request.
|
| :type api_base_url: str
| :param api_base_url: The base URL for the API endpoint.
| Typically you won't have to provide this.
| Default is the standard API base URL.
|
| :type api_version: str
| :param api_version: The version of the API to call. Typically
| you shouldn't provide this and instead use
| the default for the library. Default is the
| latest API version supported by
| google-cloud-python.
|
| :type expect_json: bool
| :param expect_json: If True, this method will try to parse the
| response as JSON and raise an exception if
| that cannot be done. Default is True.
|
| :type _target_object: :class:`object`
| :param _target_object:
| (Optional) Protected argument to be used by library callers. This
| can allow custom behavior, for example, to defer an HTTP request
| and complete initialization of the object at a later time.
|
| :type timeout: float or tuple
| :param timeout: (optional) The amount of time, in seconds, to wait
| for the server response.
|
| Can also be passed as a tuple (connect_timeout, read_timeout).
| See :meth:`requests.Session.request` documentation for details.
|
| :type extra_api_info: string
| :param extra_api_info: (optional) Extra api info to be appended to
| the X-Goog-API-Client header
|
| :raises ~google.cloud.exceptions.GoogleCloudError: if the response code
| is not 200 OK.
| :raises ValueError: if the response content type is not JSON.
| :rtype: dict or str
| :returns: The API response payload, either as a raw string or
| a dictionary if the response is valid JSON.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from google.cloud.storage._http.Connection:
|
| API_URL_TEMPLATE = '{api_base_url}/storage/{api_version}{path}'
|
| API_VERSION = 'v1'
|
| DEFAULT_API_ENDPOINT = 'https://storage.googleapis.com'
|
| DEFAULT_API_MTLS_ENDPOINT = 'https://storage.mtls.googleapis.com'
|
| ----------------------------------------------------------------------
| Methods inherited from google.cloud._http.JSONConnection:
|
| build_api_url(self, path, query_params=None, api_base_url=None, api_version=None)
| Construct an API url given a few components, some optional.
|
| Typically, you shouldn't need to use this method.
|
| :type path: str
| :param path: The path to the resource (ie, ``'/b/bucket-name'``).
|
| :type query_params: dict or list
| :param query_params: A dictionary of keys and values (or list of
| key-value pairs) to insert into the query
| string of the URL.
|
| :type api_base_url: str
| :param api_base_url: The base URL for the API endpoint.
| Typically you won't have to provide this.
|
| :type api_version: str
| :param api_version: The version of the API to call.
| Typically you shouldn't provide this and instead
| use the default for the library.
|
| :rtype: str
| :returns: The URL assembled from the pieces provided.
|
| get_api_base_url_for_mtls(self, api_base_url=None)
| Return the api base url for mutual TLS.
|
| Typically, you shouldn't need to use this method.
|
| The logic is as follows:
|
| If `api_base_url` is provided, just return this value; otherwise, the
| return value depends `GOOGLE_API_USE_MTLS_ENDPOINT` environment variable
| value.
|
| If the environment variable value is "always", return `API_BASE_MTLS_URL`.
| If the environment variable value is "never", return `API_BASE_URL`.
| Otherwise, if `ALLOW_AUTO_SWITCH_TO_MTLS_URL` is True and the underlying
| http is mTLS, then return `API_BASE_MTLS_URL`; otherwise return `API_BASE_URL`.
|
| :type api_base_url: str
| :param api_base_url: User provided api base url. It takes precedence over
| `API_BASE_URL` and `API_BASE_MTLS_URL`.
|
| :rtype: str
| :returns: The api base url used for mTLS.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from google.cloud._http.JSONConnection:
|
| ALLOW_AUTO_SWITCH_TO_MTLS_URL = False
|
| API_BASE_MTLS_URL = None
|
| API_BASE_URL = None
|
| ----------------------------------------------------------------------
| Readonly properties inherited from google.cloud._http.Connection:
|
| credentials
| Getter for current credentials.
|
| :rtype: :class:`google.auth.credentials.Credentials` or
| :class:`NoneType`
| :returns: The credentials object associated with this connection.
|
| http
| A getter for the HTTP transport used in talking to the API.
|
| Returns:
| google.auth.transport.requests.AuthorizedSession:
| A :class:`requests.Session` instance.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from google.cloud._http.Connection:
|
| USER_AGENT
| Deprecated: get / set user agent sent by connection.
|
| :rtype: str
| :returns: user agent
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| extra_headers
| Get / set extra headers sent by connection.
|
| :rtype: dict
| :returns: header keys / values
|
| user_agent
| Get / set user agent sent by connection.
|
| :rtype: str
| :returns: user agent
class MIMEApplicationHTTP(email.mime.application.MIMEApplication)
| MIMEApplicationHTTP(method, uri, headers, body)
|
| MIME type for ``application/http``.
|
| Constructs payload from headers and body
|
| :type method: str
| :param method: HTTP method
|
| :type uri: str
| :param uri: URI for HTTP request
|
| :type headers: dict
| :param headers: HTTP headers
|
| :type body: str
| :param body: (Optional) HTTP payload
|
| Method resolution order:
| MIMEApplicationHTTP
| email.mime.application.MIMEApplication
| email.mime.nonmultipart.MIMENonMultipart
| email.mime.base.MIMEBase
| email.message.Message
| builtins.object
|
| Methods defined here:
|
| __init__(self, method, uri, headers, body)
| Create an application/* type MIME document.
|
| _data contains the bytes for the raw application data.
|
| _subtype is the MIME content type subtype, defaulting to
| 'octet-stream'.
|
| _encoder is a function which will perform the actual encoding for
| transport of the application data, defaulting to base64 encoding.
|
| Any additional keyword arguments are passed to the base class
| constructor, which turns them into parameters on the Content-Type
| header.
|
| ----------------------------------------------------------------------
| Methods inherited from email.mime.nonmultipart.MIMENonMultipart:
|
| attach(self, payload)
| Add the given payload to the current payload.
|
| The current payload will always be a list of objects after this method
| is called. If you want to set the payload to a scalar object, use
| set_payload() instead.
|
| ----------------------------------------------------------------------
| Methods inherited from email.message.Message:
|
| __bytes__(self)
| Return the entire formatted message as a bytes object.
|
| __contains__(self, name)
|
| __delitem__(self, name)
| Delete all occurrences of a header, if present.
|
| Does not raise an exception if the header is missing.
|
| __getitem__(self, name)
| Get a header value.
|
| Return None if the header is missing instead of raising an exception.
|
| Note that if the header appeared multiple times, exactly which
| occurrence gets returned is undefined. Use get_all() to get all
| the values matching a header field name.
|
| __iter__(self)
|
| __len__(self)
| Return the total number of headers, including duplicates.
|
| __setitem__(self, name, val)
| Set the value of a header.
|
| Note: this does not overwrite an existing header with the same field
| name. Use __delitem__() first to delete any existing headers.
|
| __str__(self)
| Return the entire formatted message as a string.
|
| add_header(self, _name, _value, **_params)
| Extended header setting.
|
| name is the header field to add. keyword arguments can be used to set
| additional parameters for the header field, with underscores converted
| to dashes. Normally the parameter will be added as key="value" unless
| value is None, in which case only the key will be added. If a
| parameter value contains non-ASCII characters it can be specified as a
| three-tuple of (charset, language, value), in which case it will be
| encoded according to RFC2231 rules. Otherwise it will be encoded using
| the utf-8 charset and a language of ''.
|
| Examples:
|
| msg.add_header('content-disposition', 'attachment', filename='bud.gif')
| msg.add_header('content-disposition', 'attachment',
| filename=('utf-8', '', Fußballer.ppt'))
| msg.add_header('content-disposition', 'attachment',
| filename='Fußballer.ppt'))
|
| as_bytes(self, unixfrom=False, policy=None)
| Return the entire formatted message as a bytes object.
|
| Optional 'unixfrom', when true, means include the Unix From_ envelope
| header. 'policy' is passed to the BytesGenerator instance used to
| serialize the message; if not specified the policy associated with
| the message instance is used.
|
| as_string(self, unixfrom=False, maxheaderlen=0, policy=None)
| Return the entire formatted message as a string.
|
| Optional 'unixfrom', when true, means include the Unix From_ envelope
| header. For backward compatibility reasons, if maxheaderlen is
| not specified it defaults to 0, so you must override it explicitly
| if you want a different maxheaderlen. 'policy' is passed to the
| Generator instance used to serialize the message; if it is not
| specified the policy associated with the message instance is used.
|
| If the message object contains binary data that is not encoded
| according to RFC standards, the non-compliant data will be replaced by
| unicode "unknown character" code points.
|
| del_param(self, param, header='content-type', requote=True)
| Remove the given parameter completely from the Content-Type header.
|
| The header will be re-written in place without the parameter or its
| value. All values will be quoted as necessary unless requote is
| False. Optional header specifies an alternative to the Content-Type
| header.
|
| get(self, name, failobj=None)
| Get a header value.
|
| Like __getitem__() but return failobj instead of None when the field
| is missing.
|
| get_all(self, name, failobj=None)
| Return a list of all the values for the named field.
|
| These will be sorted in the order they appeared in the original
| message, and may contain duplicates. Any fields deleted and
| re-inserted are always appended to the header list.
|
| If no such fields exist, failobj is returned (defaults to None).
|
| get_boundary(self, failobj=None)
| Return the boundary associated with the payload if present.
|
| The boundary is extracted from the Content-Type header's `boundary'
| parameter, and it is unquoted.
|
| get_charset(self)
| Return the Charset instance associated with the message's payload.
|
| get_charsets(self, failobj=None)
| Return a list containing the charset(s) used in this message.
|
| The returned list of items describes the Content-Type headers'
| charset parameter for this message and all the subparts in its
| payload.
|
| Each item will either be a string (the value of the charset parameter
| in the Content-Type header of that part) or the value of the
| 'failobj' parameter (defaults to None), if the part does not have a
| main MIME type of "text", or the charset is not defined.
|
| The list will contain one string for each part of the message, plus
| one for the container message (i.e. self), so that a non-multipart
| message will still return a list of length 1.
|
| get_content_charset(self, failobj=None)
| Return the charset parameter of the Content-Type header.
|
| The returned string is always coerced to lower case. If there is no
| Content-Type header, or if that header has no charset parameter,
| failobj is returned.
|
| get_content_disposition(self)
| Return the message's content-disposition if it exists, or None.
|
| The return values can be either 'inline', 'attachment' or None
| according to the rfc2183.
|
| get_content_maintype(self)
| Return the message's main content type.
|
| This is the `maintype' part of the string returned by
| get_content_type().
|
| get_content_subtype(self)
| Returns the message's sub-content type.
|
| This is the `subtype' part of the string returned by
| get_content_type().
|
| get_content_type(self)
| Return the message's content type.
|
| The returned string is coerced to lower case of the form
| `maintype/subtype'. If there was no Content-Type header in the
| message, the default type as given by get_default_type() will be
| returned. Since according to RFC 2045, messages always have a default
| type this will always return a value.
|
| RFC 2045 defines a message's default type to be text/plain unless it
| appears inside a multipart/digest container, in which case it would be
| message/rfc822.
|
| get_default_type(self)
| Return the `default' content type.
|
| Most messages have a default content type of text/plain, except for
| messages that are subparts of multipart/digest containers. Such
| subparts have a default content type of message/rfc822.
|
| get_filename(self, failobj=None)
| Return the filename associated with the payload if present.
|
| The filename is extracted from the Content-Disposition header's
| `filename' parameter, and it is unquoted. If that header is missing
| the `filename' parameter, this method falls back to looking for the
| `name' parameter.
|
| get_param(self, param, failobj=None, header='content-type', unquote=True)
| Return the parameter value if found in the Content-Type header.
|
| Optional failobj is the object to return if there is no Content-Type
| header, or the Content-Type header has no such parameter. Optional
| header is the header to search instead of Content-Type.
|
| Parameter keys are always compared case insensitively. The return
| value can either be a string, or a 3-tuple if the parameter was RFC
| 2231 encoded. When it's a 3-tuple, the elements of the value are of
| the form (CHARSET, LANGUAGE, VALUE). Note that both CHARSET and
| LANGUAGE can be None, in which case you should consider VALUE to be
| encoded in the us-ascii charset. You can usually ignore LANGUAGE.
| The parameter value (either the returned string, or the VALUE item in
| the 3-tuple) is always unquoted, unless unquote is set to False.
|
| If your application doesn't care whether the parameter was RFC 2231
| encoded, it can turn the return value into a string as follows:
|
| rawparam = msg.get_param('foo')
| param = email.utils.collapse_rfc2231_value(rawparam)
|
| get_params(self, failobj=None, header='content-type', unquote=True)
| Return the message's Content-Type parameters, as a list.
|
| The elements of the returned list are 2-tuples of key/value pairs, as
| split on the `=' sign. The left hand side of the `=' is the key,
| while the right hand side is the value. If there is no `=' sign in
| the parameter the value is the empty string. The value is as
| described in the get_param() method.
|
| Optional failobj is the object to return if there is no Content-Type
| header. Optional header is the header to search instead of
| Content-Type. If unquote is True, the value is unquoted.
|
| get_payload(self, i=None, decode=False)
| Return a reference to the payload.
|
| The payload will either be a list object or a string. If you mutate
| the list object, you modify the message's payload in place. Optional
| i returns that index into the payload.
|
| Optional decode is a flag indicating whether the payload should be
| decoded or not, according to the Content-Transfer-Encoding header
| (default is False).
|
| When True and the message is not a multipart, the payload will be
| decoded if this header's value is `quoted-printable' or `base64'. If
| some other encoding is used, or the header is missing, or if the
| payload has bogus data (i.e. bogus base64 or uuencoded data), the
| payload is returned as-is.
|
| If the message is a multipart and the decode flag is True, then None
| is returned.
|
| get_unixfrom(self)
|
| is_multipart(self)
| Return True if the message consists of multiple parts.
|
| items(self)
| Get all the message's header fields and values.
|
| These will be sorted in the order they appeared in the original
| message, or were added to the message, and may contain duplicates.
| Any fields deleted and re-inserted are always appended to the header
| list.
|
| keys(self)
| Return a list of all the message's header field names.
|
| These will be sorted in the order they appeared in the original
| message, or were added to the message, and may contain duplicates.
| Any fields deleted and re-inserted are always appended to the header
| list.
|
| raw_items(self)
| Return the (name, value) header pairs without modification.
|
| This is an "internal" API, intended only for use by a generator.
|
| replace_header(self, _name, _value)
| Replace a header.
|
| Replace the first matching header found in the message, retaining
| header order and case. If no matching header was found, a KeyError is
| raised.
|
| set_boundary(self, boundary)
| Set the boundary parameter in Content-Type to 'boundary'.
|
| This is subtly different than deleting the Content-Type header and
| adding a new one with a new boundary parameter via add_header(). The
| main difference is that using the set_boundary() method preserves the
| order of the Content-Type header in the original message.
|
| HeaderParseError is raised if the message has no Content-Type header.
|
| set_charset(self, charset)
| Set the charset of the payload to a given character set.
|
| charset can be a Charset instance, a string naming a character set, or
| None. If it is a string it will be converted to a Charset instance.
| If charset is None, the charset parameter will be removed from the
| Content-Type field. Anything else will generate a TypeError.
|
| The message will be assumed to be of type text/* encoded with
| charset.input_charset. It will be converted to charset.output_charset
| and encoded properly, if needed, when generating the plain text
| representation of the message. MIME headers (MIME-Version,
| Content-Type, Content-Transfer-Encoding) will be added as needed.
|
| set_default_type(self, ctype)
| Set the `default' content type.
|
| ctype should be either "text/plain" or "message/rfc822", although this
| is not enforced. The default content type is not stored in the
| Content-Type header.
|
| set_param(self, param, value, header='Content-Type', requote=True, charset=None, language='', replace=False)
| Set a parameter in the Content-Type header.
|
| If the parameter already exists in the header, its value will be
| replaced with the new value.
|
| If header is Content-Type and has not yet been defined for this
| message, it will be set to "text/plain" and the new parameter and
| value will be appended as per RFC 2045.
|
| An alternate header can be specified in the header argument, and all
| parameters will be quoted as necessary unless requote is False.
|
| If charset is specified, the parameter will be encoded according to RFC
| 2231. Optional language specifies the RFC 2231 language, defaulting
| to the empty string. Both charset and language should be strings.
|
| set_payload(self, payload, charset=None)
| Set the payload to the given value.
|
| Optional charset sets the message's default character set. See
| set_charset() for details.
|
| set_raw(self, name, value)
| Store name and value in the model without modification.
|
| This is an "internal" API, intended only for use by a parser.
|
| set_type(self, type, header='Content-Type', requote=True)
| Set the main type and subtype for the Content-Type header.
|
| type must be a string in the form "maintype/subtype", otherwise a
| ValueError is raised.
|
| This method replaces the Content-Type header, keeping all the
| parameters in place. If requote is False, this leaves the existing
| header's quoting as is. Otherwise, the parameters will be quoted (the
| default).
|
| An alternative header can be specified in the header argument. When
| the Content-Type header is set, we'll always also add a MIME-Version
| header.
|
| set_unixfrom(self, unixfrom)
| # Unix From_ line
|
| values(self)
| Return a list of all the message's header values.
|
| These will be sorted in the order they appeared in the original
| message, or were added to the message, and may contain duplicates.
| Any fields deleted and re-inserted are always appended to the header
| list.
|
| walk(self) from email.iterators
| Walk over the message tree, yielding each subpart.
|
| The walk is performed in depth-first order. This method is a
| generator.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from email.message.Message:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\google\cloud\storage\batch.py
google-cloud-storage.blob
Python Library Documentation: module google.cloud.storage.blob in google.cloud.storage
NAME
google.cloud.storage.blob - Create / interact with Google Cloud Storage blobs.
CLASSES
builtins.dict(builtins.object)
ObjectContexts
ObjectCustomContextPayload
Retention
google.cloud.storage._helpers._PropertyMixin(builtins.object)
Blob
class Blob(google.cloud.storage._helpers._PropertyMixin)
| Blob(name, bucket, chunk_size=None, encryption_key=None, kms_key_name=None, generation=None)
|
| A wrapper around Cloud Storage's concept of an ``Object``.
|
| :type name: str
| :param name: The name of the blob. This corresponds to the unique path of
| the object in the bucket. If bytes, will be converted to a
| unicode object. Blob / object names can contain any sequence
| of valid unicode characters, of length 1-1024 bytes when
| UTF-8 encoded.
|
| :type bucket: :class:`google.cloud.storage.bucket.Bucket`
| :param bucket: The bucket to which this blob belongs.
|
| :type chunk_size: int
| :param chunk_size:
| (Optional) The size of a chunk of data whenever iterating (in bytes).
| This must be a multiple of 256 KB per the API specification. If not
| specified, the chunk_size of the blob itself is used. If that is not
| specified, a default value of 40 MB is used.
|
| :type encryption_key: bytes
| :param encryption_key:
| (Optional) 32 byte encryption key for customer-supplied encryption.
| See https://cloud.google.com/storage/docs/encryption#customer-supplied.
|
| :type kms_key_name: str
| :param kms_key_name:
| (Optional) Resource name of Cloud KMS key used to encrypt the blob's
| contents.
|
| :type generation: long
| :param generation:
| (Optional) If present, selects a specific revision of this object.
|
| Method resolution order:
| Blob
| google.cloud.storage._helpers._PropertyMixin
| builtins.object
|
| Methods defined here:
|
| __init__(self, name, bucket, chunk_size=None, encryption_key=None, kms_key_name=None, generation=None)
| property :attr:`name`
| Get the blob's name.
|
| __repr__(self)
| Return repr(self).
|
| compose(self, sources, client=None, timeout=60, if_generation_match=None, if_metageneration_match=None, if_source_generation_match=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2CF29F40>, destination_contexts=None, delete_source_objects=None)
| Concatenate source blobs into this one.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/objects/compose)
| and a [code sample](https://cloud.google.com/storage/docs/samples/storage-compose-file#storage_compose_file-python).
|
| :type sources: list of :class:`Blob`
| :param sources: Blobs whose contents will be composed into this blob.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) Makes the operation conditional on whether the
| destination object's current generation matches the given value.
| Setting to 0 makes the operation succeed only if there are no live
| versions of the object.
| Note: In a previous version, this argument worked identically to the
| ``if_source_generation_match`` argument. For
| backwards-compatibility reasons, if a list is passed in,
| this argument will behave like ``if_source_generation_match``
| and also issue a DeprecationWarning.
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) Makes the operation conditional on whether the
| destination object's current metageneration matches the given
| value.
|
| If a list of long is passed in, no match operation will be
| performed. (Deprecated: type(list of long) is supported for
| backwards-compatability reasons only.)
|
| :type if_source_generation_match: list of long
| :param if_source_generation_match:
| (Optional) Makes the operation conditional on whether the current
| generation of each source blob matches the corresponding generation.
| The list must match ``sources`` item-to-item.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC.
| The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
| policy which will only enable retries if ``if_generation_match`` or ``generation``
| is set, in order to ensure requests are idempotent before retrying them.
| Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
| to enable retries regardless of generation precondition setting.
| See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| :type destination_contexts: :class:`~google.cloud.storage.blob.ObjectContexts`
| :param destination_contexts:
| (Optional) New contexts to set for the destination object.
| See: https://docs.cloud.google.com/storage/docs/use-object-contexts#manage_object_contexts_during_object_operations
|
| :type delete_source_objects: bool
| :param delete_source_objects:
| (Optional) If True, the source objects will be deleted after a
| successful composition.
|
| create_resumable_upload_session(self, content_type=None, size=None, origin=None, client=None, timeout=60, checksum='auto', predefined_acl=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Create a resumable upload session.
|
| Resumable upload sessions allow you to start an upload session from
| one client and complete the session in another. This method is called
| by the initiator to set the metadata and limits. The initiator then
| passes the session URL to the client that will upload the binary data.
| The client performs a PUT request on the session URL to complete the
| upload. This process allows untrusted clients to upload to an
| access-controlled bucket.
|
| For more details, see the
| documentation on [`signed URLs`](https://cloud.google.com/storage/docs/access-control/signed-urls#signing-resumable).
|
| The content type of the upload will be determined in order
| of precedence:
|
| - The value passed in to this method (if not :data:`None`)
| - The value stored on the current blob
| - The default value ('application/octet-stream')
|
| .. note::
| The effect of uploading to an existing blob depends on the
| "versioning" and "lifecycle" policies defined on the blob's
| bucket. In the absence of those policies, upload will
| overwrite any existing contents.
|
| See the [`object versioning`](https://cloud.google.com/storage/docs/object-versioning)
| and [`lifecycle`](https://cloud.google.com/storage/docs/lifecycle)
| API documents for details.
|
| If :attr:`encryption_key` is set, the blob will be encrypted with
| a [`customer-supplied`](https://cloud.google.com/storage/docs/encryption#customer-supplied)
| encryption key.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type size: int
| :param size:
| (Optional) The maximum number of bytes that can be uploaded using
| this session. If the size is not known when creating the session,
| this should be left blank.
|
| :type content_type: str
| :param content_type: (Optional) Type of content being uploaded.
|
| :type origin: str
| :param origin:
| (Optional) If set, the upload can only be completed by a user-agent
| that uploads from the given origin. This can be useful when passing
| the session to a web client.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type checksum: str
| :param checksum:
| (Optional) The type of checksum to compute to verify
| the integrity of the object. After the upload is complete, the
| server-computed checksum of the resulting object will be checked
| and google.cloud.storage.exceptions.DataCorruption will be raised on
| a mismatch. On a validation failure, the client will attempt to
| delete the uploaded object automatically. 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.
|
| :type predefined_acl: str
| :param predefined_acl: (Optional) Predefined access control list
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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_generation_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.
|
| :rtype: str
| :returns: The resumable upload session URL. The upload can be
| completed by making an HTTP PUT request with the
| file's contents.
|
| :raises: :class:`google.cloud.exceptions.GoogleCloudError`
| if the session creation response returns an error status.
|
| delete(self, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Deletes a blob from Cloud Storage.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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_generation_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.
|
| :raises: :class:`google.cloud.exceptions.NotFound`
| (propagated from
| :meth:`google.cloud.storage.bucket.Bucket.delete_blob`).
|
| download_as_bytes(self, client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='auto', retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, single_shot_download=False)
| Download the contents of this blob as a bytes object.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type start: int
| :param start: (Optional) The first byte in a range to be downloaded.
|
| :type end: int
| :param end: (Optional) The last byte in a range to be downloaded.
|
| :type raw_download: bool
| :param raw_download:
| (Optional) If true, download the object without any expansion.
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match:
| (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]]
| :param if_etag_not_match:
| (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type checksum: str
| :param checksum:
| (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.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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 single_shot_download: bool
| :param single_shot_download:
| (Optional) If true, download the object in a single request.
| Caution: Enabling this will increase the memory overload for your application.
| Please enable this as per your use case.
|
| :rtype: bytes
| :returns: The data stored in this blob.
|
| :raises: :class:`google.cloud.exceptions.NotFound`
|
| download_as_string(self, client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, single_shot_download=False)
| (Deprecated) Download the contents of this blob as a bytes object.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| .. note::
| Deprecated alias for :meth:`download_as_bytes`.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type start: int
| :param start: (Optional) The first byte in a range to be downloaded.
|
| :type end: int
| :param end: (Optional) The last byte in a range to be downloaded.
|
| :type raw_download: bool
| :param raw_download:
| (Optional) If true, download the object without any expansion.
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match:
| (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]]
| :param if_etag_not_match:
| (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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 single_shot_download: bool
| :param single_shot_download:
| (Optional) If true, download the object in a single request.
| Caution: Enabling this will increase the memory overload for your application.
| Please enable this as per your use case.
|
| :rtype: bytes
| :returns: The data stored in this blob.
|
| :raises: :class:`google.cloud.exceptions.NotFound`
|
| download_as_text(self, client=None, start=None, end=None, raw_download=False, encoding=None, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, single_shot_download=False)
| Download the contents of this blob as text (*not* bytes).
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type start: int
| :param start: (Optional) The first byte in a range to be downloaded.
|
| :type end: int
| :param end: (Optional) The last byte in a range to be downloaded.
|
| :type raw_download: bool
| :param raw_download:
| (Optional) If true, download the object without any expansion.
|
| :type encoding: str
| :param encoding: (Optional) encoding to be used to decode the
| downloaded bytes. Defaults to the ``charset`` param of
| attr:`content_type`, or else to "utf-8".
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match:
| (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]]
| :param if_etag_not_match:
| (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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 single_shot_download: bool
| :param single_shot_download:
| (Optional) If true, download the object in a single request.
| Caution: Enabling this will increase the memory overload for your application.
| Please enable this as per your use case.
|
| :rtype: text
| :returns: The data stored in this blob, decoded to text.
|
| download_to_file(self, file_obj, client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='auto', retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, single_shot_download=False)
| Download the contents of this blob into a file-like object.
|
| .. note::
|
| If the server-set property, :attr:`media_link`, is not yet
| initialized, makes an additional API request to load it.
|
| If the :attr:`chunk_size` of a current blob is `None`, will download data
| in single download request otherwise it will download the :attr:`chunk_size`
| of data in each request.
|
| For more fine-grained control over the download process, check out
| [`google-resumable-media`](https://googleapis.dev/python/google-resumable-media/latest/index.html).
| For example, this library allows downloading **parts** of a blob rather than the whole thing.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type file_obj: file
| :param file_obj: A file handle to which to write the blob's data.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type start: int
| :param start: (Optional) The first byte in a range to be downloaded.
|
| :type end: int
| :param end: (Optional) The last byte in a range to be downloaded.
|
| :type raw_download: bool
| :param raw_download:
| (Optional) If true, download the object without any expansion.
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match:
| (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]]
| :param if_etag_not_match:
| (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type checksum: str
| :param checksum:
| (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.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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 single_shot_download: bool
| :param single_shot_download:
| (Optional) If true, download the object in a single request.
| Caution: Enabling this will increase the memory overload for your application.
| Please enable this as per your use case.
|
| :raises: :class:`google.cloud.exceptions.NotFound`
|
| download_to_filename(self, filename, client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='auto', retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, single_shot_download=False)
| Download the contents of this blob into a named file.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| See a [code sample](https://cloud.google.com/storage/docs/samples/storage-download-encrypted-file#storage_download_encrypted_file-python)
| to download a file with a [`customer-supplied encryption key`](https://cloud.google.com/storage/docs/encryption#customer-supplied).
|
| :type filename: str
| :param filename: A filename to be passed to ``open``.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type start: int
| :param start: (Optional) The first byte in a range to be downloaded.
|
| :type end: int
| :param end: (Optional) The last byte in a range to be downloaded.
|
| :type raw_download: bool
| :param raw_download:
| (Optional) If true, download the object without any expansion.
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match:
| (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]]
| :param if_etag_not_match:
| (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type checksum: str
| :param checksum:
| (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.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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 single_shot_download: bool
| :param single_shot_download:
| (Optional) If true, download the object in a single request.
| Caution: Enabling this will increase the memory overload for your application.
| Please enable this as per your use case.
|
| :raises: :class:`google.cloud.exceptions.NotFound`
|
| exists(self, client=None, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, soft_deleted=None)
| Determines whether or not this blob exists.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match:
| (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]]
| :param if_etag_not_match:
| (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type soft_deleted: bool
| :param soft_deleted:
| (Optional) If True, looks for a soft-deleted object. Will only return True
| if the object exists and is in a soft-deleted state.
| :attr:`generation` is required to be set on the blob if ``soft_deleted`` is set to True.
| See: https://cloud.google.com/storage/docs/soft-delete
|
| :rtype: bool
| :returns: True if the blob exists in Cloud Storage.
|
| generate_signed_url(self, expiration=None, api_access_endpoint=None, method='GET', content_md5=None, content_type=None, response_disposition=None, response_type=None, generation=None, headers=None, query_parameters=None, client=None, credentials=None, version=None, service_account_email=None, access_token=None, virtual_hosted_style=False, bucket_bound_hostname=None, scheme='http')
| Generates a signed URL for this blob.
|
| .. note::
|
| If you are on Google Compute Engine, you can't generate a signed
| URL using GCE service account.
| If you'd like to be able to generate a signed URL from GCE,
| you can use a standard service account from a JSON file rather
| than a GCE service account.
|
| If you have a blob that you want to allow access to for a set
| amount of time, you can use this method to generate a URL that
| is only valid within a certain time period.
|
| See a [code sample](https://cloud.google.com/storage/docs/samples/storage-generate-signed-url-v4#storage_generate_signed_url_v4-python).
|
| This is particularly useful if you don't want publicly
| accessible blobs, but don't want to require users to explicitly
| log in.
|
| If ``bucket_bound_hostname`` is set as an argument of :attr:`api_access_endpoint`,
| ``https`` works only if using a ``CDN``.
|
| :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
| :param expiration:
| Point in time when the signed URL should expire. If a ``datetime``
| instance is passed without an explicit ``tzinfo`` set, it will be
| assumed to be ``UTC``.
|
| :type api_access_endpoint: str
| :param api_access_endpoint: (Optional) URI base, for instance
| "https://storage.googleapis.com". If not specified, the client's
| api_endpoint will be used. Incompatible with bucket_bound_hostname.
|
| :type method: str
| :param method: The HTTP verb that will be used when requesting the URL.
|
| :type content_md5: str
| :param content_md5:
| (Optional) The MD5 hash of the object referenced by ``resource``.
|
| :type content_type: str
| :param content_type:
| (Optional) The content type of the object referenced by
| ``resource``.
|
| :type response_disposition: str
| :param response_disposition:
| (Optional) Content disposition of responses to requests for the
| signed URL. For example, to enable the signed URL to initiate a
| file of ``blog.png``, use the value ``'attachment;
| filename=blob.png'``.
|
| :type response_type: str
| :param response_type:
| (Optional) Content type of responses to requests for the signed
| URL. Ignored if content_type is set on object/blob metadata.
|
| :type generation: str
| :param generation:
| (Optional) A value that indicates which generation of the resource
| to fetch.
|
| :type headers: dict
| :param headers:
| (Optional) Additional HTTP headers to be included as part of the
| signed URLs. See:
| https://cloud.google.com/storage/docs/xml-api/reference-headers
| Requests using the signed URL *must* pass the specified header
| (name and value) with each request for the URL.
|
| :type query_parameters: dict
| :param query_parameters:
| (Optional) Additional query parameters to be included as part of the
| signed URLs. See:
| https://cloud.google.com/storage/docs/xml-api/reference-headers#query
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type credentials: :class:`google.auth.credentials.Credentials`
| :param credentials:
| (Optional) The authorization credentials to attach to requests.
| These credentials identify this application to the service. If
| none are specified, the client will attempt to ascertain the
| credentials from the environment.
|
| :type version: str
| :param version:
| (Optional) The version of signed credential to create. Must be one
| of 'v2' | 'v4'.
|
| :type service_account_email: str
| :param service_account_email:
| (Optional) E-mail address of the service account.
|
| :type access_token: str
| :param access_token: (Optional) Access token for a service account.
|
| :type virtual_hosted_style: bool
| :param virtual_hosted_style:
| (Optional) If true, then construct the URL relative the bucket's
| virtual hostname, e.g., '<bucket-name>.storage.googleapis.com'.
| Incompatible with bucket_bound_hostname.
|
| :type bucket_bound_hostname: str
| :param bucket_bound_hostname:
| (Optional) If passed, then construct the URL relative to the bucket-bound hostname.
| Value can be a bare or with scheme, e.g., 'example.com' or 'http://example.com'.
| Incompatible with api_access_endpoint and virtual_hosted_style.
| See: https://cloud.google.com/storage/docs/request-endpoints#cname
|
| :type scheme: str
| :param scheme:
| (Optional) If ``bucket_bound_hostname`` is passed as a bare
| hostname, use this value as the scheme. ``https`` will work only
| when using a CDN. Defaults to ``"http"``.
|
| :raises: :exc:`ValueError` when version is invalid or mutually exclusive arguments are used.
| :raises: :exc:`TypeError` when expiration is not a valid type.
| :raises: :exc:`AttributeError` if credentials is not an instance
| of :class:`google.auth.credentials.Signing`.
|
| :rtype: str
| :returns: A signed URL you can use to access the resource
| until expiration.
|
| get_iam_policy(self, client=None, requested_policy_version=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Retrieve the IAM policy for the object.
|
| .. note::
|
| Blob- / object-level IAM support does not yet exist and methods
| currently call an internal ACL backend not providing any utility
| beyond the blob's :attr:`acl` at this time. The API may be enhanced
| in the future and is currently undocumented. Use :attr:`acl` for
| managing object access control.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the current object's bucket.
|
| :type requested_policy_version: int or ``NoneType``
| :param requested_policy_version:
| (Optional) The version of IAM policies to request. If a policy
| with a condition is requested without setting this, the server will
| return an error. This must be set to a value of 3 to retrieve IAM
| policies containing conditions. This is to prevent client code that
| isn't aware of IAM conditions from interpreting and modifying
| policies incorrectly. The service might return a policy with
| version lower than the one that was requested, based on the feature
| syntax in the policy fetched.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: :class:`google.api_core.iam.Policy`
| :returns: the policy instance, based on the resource returned from
| the ``getIamPolicy`` API request.
|
| make_private(self, client=None, timeout=60, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Update blob's ACL, revoking read access for anonymous users.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the blob's bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| make_public(self, client=None, timeout=60, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Update blob's ACL, granting read access to anonymous users.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the blob's bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| open(self, mode='r', chunk_size=None, ignore_flush=None, encoding=None, errors=None, newline=None, **kwargs)
| Create a file handler for file-like I/O to or from this blob.
|
| This method can be used as a context manager, just like Python's
| built-in 'open()' function.
|
| While reading, as with other read methods, if blob.generation is not set
| the most recent blob generation will be used. Because the file-like IO
| reader downloads progressively in chunks, this could result in data from
| multiple versions being mixed together. If this is a concern, use
| either bucket.get_blob(), or blob.reload(), which will download the
| latest generation number and set it; or, if the generation is known, set
| it manually, for instance with bucket.blob(generation=123456).
|
| Checksumming (hashing) to verify data integrity is disabled for reads
| using this feature because reads are implemented using request ranges,
| which do not provide checksums to validate. See
| https://cloud.google.com/storage/docs/hashes-etags for details.
|
| See a [code sample](https://github.com/googleapis/python-storage/blob/main/samples/snippets/storage_fileio_write_read.py).
|
| Keyword arguments to pass to the underlying API calls.
| For both uploads and downloads, the following arguments are
| supported:
|
| - ``if_generation_match``
| - ``if_generation_not_match``
| - ``if_metageneration_match``
| - ``if_metageneration_not_match``
| - ``timeout``
| - ``retry``
|
| For downloads only, the following additional arguments are supported:
|
| - ``raw_download``
| - ``single_shot_download``
|
| For uploads only, the following additional arguments are supported:
|
| - ``content_type``
| - ``predefined_acl``
| - ``checksum``
|
| :type mode: str
| :param mode:
| (Optional) A mode string, as per standard Python `open()` semantics.The first
| character must be 'r', to open the blob for reading, or 'w' to open
| it for writing. The second character, if present, must be 't' for
| (unicode) text mode, or 'b' for bytes mode. If the second character
| is omitted, text mode is the default.
|
| :type chunk_size: long
| :param chunk_size:
| (Optional) For reads, the minimum number of bytes to read at a time.
| If fewer bytes than the chunk_size are requested, the remainder is
| buffered. For writes, the maximum number of bytes to buffer before
| sending data to the server, and the size of each request when data
| is sent. Writes are implemented as a "resumable upload", so
| chunk_size for writes must be exactly a multiple of 256KiB as with
| other resumable uploads. The default is 40 MiB.
|
| :type ignore_flush: bool
| :param ignore_flush:
| (Optional) For non text-mode writes, makes flush() do nothing
| instead of raising an error. flush() without closing is not
| supported by the remote service and therefore calling it normally
| results in io.UnsupportedOperation. However, that behavior is
| incompatible with some consumers and wrappers of file objects in
| Python, such as zipfile.ZipFile or io.TextIOWrapper. Setting
| ignore_flush will cause flush() to successfully do nothing, for
| compatibility with those contexts. The correct way to actually flush
| data to the remote server is to close() (using a context manager,
| such as in the example, will cause this to happen automatically).
|
| :type encoding: str
| :param encoding:
| (Optional) For text mode only, the name of the encoding that the stream will
| be decoded or encoded with. If omitted, it defaults to
| locale.getpreferredencoding(False).
|
| :type errors: str
| :param errors:
| (Optional) For text mode only, an optional string that specifies how encoding
| and decoding errors are to be handled. Pass 'strict' to raise a
| ValueError exception if there is an encoding error (the default of
| None has the same effect), or pass 'ignore' to ignore errors. (Note
| that ignoring encoding errors can lead to data loss.) Other more
| rarely-used options are also available; see the Python 'io' module
| documentation for 'io.TextIOWrapper' for a complete list.
|
| :type newline: str
| :param newline:
| (Optional) For text mode only, controls how line endings are handled. It can
| be None, '', '\n', '\r', and '\r\n'. If None, reads use "universal
| newline mode" and writes use the system default. See the Python
| 'io' module documentation for 'io.TextIOWrapper' for details.
|
| :returns: A 'BlobReader' or 'BlobWriter' from
| 'google.cloud.storage.fileio', or an 'io.TextIOWrapper' around one
| of those classes, depending on the 'mode' argument.
|
| rewrite(self, source, token=None, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, if_source_generation_match=None, if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2CF29F40>, destination_contexts=None)
| Rewrite source blob into this one.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| .. note::
|
| ``rewrite`` is not supported in a ``Batch`` context.
|
| :type source: :class:`Blob`
| :param source: blob whose contents will be rewritten into this blob.
|
| :type token: str
| :param token:
| (Optional) Token returned from an earlier, not-completed call to
| rewrite the same source blob. If passed, result will include
| updated status, total bytes written.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_source_generation_match: long
| :param if_source_generation_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation matches the given value.
|
| :type if_source_generation_not_match: long
| :param if_source_generation_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation does not match the given value.
|
| :type if_source_metageneration_match: long
| :param if_source_metageneration_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration matches the given value.
|
| :type if_source_metageneration_not_match: long
| :param if_source_metageneration_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration does not match the given value.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC.
| The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
| policy which will only enable retries if ``if_generation_match`` or ``generation``
| is set, in order to ensure requests are idempotent before retrying them.
| Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
| to enable retries regardless of generation precondition setting.
| See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| :type destination_contexts: :class:`~google.cloud.storage.blob.ObjectContexts` or dict
| :param destination_contexts:
| (Optional) New contexts to set for the destination object.
| See: https://docs.cloud.google.com/storage/docs/use-object-contexts#manage_object_contexts_during_object_operations
|
| :rtype: tuple
| :returns: ``(token, bytes_rewritten, total_bytes)``, where ``token``
| is a rewrite token (``None`` if the rewrite is complete),
| ``bytes_rewritten`` is the number of bytes rewritten so far,
| and ``total_bytes`` is the total number of bytes to be
| rewritten.
|
| set_iam_policy(self, policy, client=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920980>)
| Update the IAM policy for the bucket.
|
| .. note::
|
| Blob- / object-level IAM support does not yet exist and methods
| currently call an internal ACL backend not providing any utility
| beyond the blob's :attr:`acl` at this time. The API may be enhanced
| in the future and is currently undocumented. Use :attr:`acl` for
| managing object access control.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type policy: :class:`google.api_core.iam.Policy`
| :param policy: policy instance used to update bucket's IAM policy.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the current bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: :class:`google.api_core.iam.Policy`
| :returns: the policy instance, based on the resource returned from
| the ``setIamPolicy`` API request.
|
| test_iam_permissions(self, permissions, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| API call: test permissions
|
| .. note::
|
| Blob- / object-level IAM support does not yet exist and methods
| currently call an internal ACL backend not providing any utility
| beyond the blob's :attr:`acl` at this time. The API may be enhanced
| in the future and is currently undocumented. Use :attr:`acl` for
| managing object access control.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type permissions: list of string
| :param permissions: the permissions to check
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the current bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: list of string
| :returns: the permissions returned by the ``testIamPermissions`` API
| request.
|
| update_storage_class(self, new_class, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, if_source_generation_match=None, if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2CF29F40>)
| Update blob's storage class via a rewrite-in-place. This helper will
| wait for the rewrite to complete before returning, so it may take some
| time for large files.
|
| See
| https://cloud.google.com/storage/docs/per-object-storage-class
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type new_class: str
| :param new_class:
| new storage class for the object. One of:
| :attr:`~google.cloud.storage.constants.NEARLINE_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.COLDLINE_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.ARCHIVE_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.STANDARD_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.MULTI_REGIONAL_LEGACY_STORAGE_CLASS`,
| or
| :attr:`~google.cloud.storage.constants.REGIONAL_LEGACY_STORAGE_CLASS`.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_source_generation_match: long
| :param if_source_generation_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation matches the given value.
|
| :type if_source_generation_not_match: long
| :param if_source_generation_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation does not match the given value.
|
| :type if_source_metageneration_match: long
| :param if_source_metageneration_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration matches the given value.
|
| :type if_source_metageneration_not_match: long
| :param if_source_metageneration_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration does not match the given value.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC.
| The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
| policy which will only enable retries if ``if_generation_match`` or ``generation``
| is set, in order to ensure requests are idempotent before retrying them.
| Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
| to enable retries regardless of generation precondition setting.
| See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| upload_from_file(self, file_obj, rewind=False, size=None, content_type=None, client=None, predefined_acl=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='auto', retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, crc32c_checksum_value=None)
| Upload the contents of this blob from a file-like object.
|
| The content type of the upload will be determined in order
| of precedence:
|
| - The value passed in to this method (if not :data:`None`)
| - The value stored on the current blob
| - The default value ('application/octet-stream')
|
| .. note::
| The effect of uploading to an existing blob depends on the
| "versioning" and "lifecycle" policies defined on the blob's
| bucket. In the absence of those policies, upload will
| overwrite any existing contents.
|
| See the [`object versioning`](https://cloud.google.com/storage/docs/object-versioning)
| and [`lifecycle`](https://cloud.google.com/storage/docs/lifecycle)
| API documents for details.
|
| If the size of the data to be uploaded exceeds 8 MB a resumable media
| request will be used, otherwise the content and the metadata will be
| uploaded in a single multipart upload request.
|
| For more fine-grained over the upload process, check out
| [`google-resumable-media`](https://googleapis.dev/python/google-resumable-media/latest/index.html).
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type file_obj: file
| :param file_obj: A file handle opened in binary mode for reading.
|
| :type rewind: bool
| :param rewind:
| If True, seek to the beginning of the file handle before writing
| the file to Cloud Storage.
|
| :type size: int
| :param size:
| The number of bytes to be uploaded (which will be read from
| ``file_obj``). If not provided, the upload will be concluded once
| ``file_obj`` is exhausted.
|
| :type content_type: str
| :param content_type: (Optional) Type of content being uploaded.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type predefined_acl: str
| :param predefined_acl: (Optional) Predefined access control list
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type checksum: str
| :param checksum:
| (Optional) The type of checksum to compute to verify
| the integrity of the object. If the upload is completed in a single
| request, the checksum will be entirely precomputed and the remote
| server will handle verification and error handling. If the upload
| is too large and must be transmitted in multiple requests, the
| checksum will be incrementally computed and the client will handle
| verification and error handling, raising
| google.cloud.storage.exceptions.DataCorruption on a mismatch and
| attempting to delete the corrupted file. 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.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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_generation_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 crc32c_checksum_value: str
| :param crc32c_checksum_value: (Optional) This should be the checksum of
| the entire contents of `file_obj`. Applicable while uploading object
| greater than `_MAX_MULTIPART_SIZE` bytes.
|
| It can be obtained by running
|
| `gcloud storage hash /path/to/your/file`
|
| or
|
| .. code-block:: python
|
| import google_crc32c
| import base64
|
| data = b"Hello, world!"
| crc32c_int = google_crc32c.value(data)
| crc32c_hex = f"{crc32c_int:08x}"
| crc32c_bytes = crc32c_int.to_bytes(4, "big")
| base64_encoded = base64.b64encode(crc32c_bytes)
| crc32c_base64 = base64_encoded.decode("utf-8")
|
| print(crc32c_base64)
|
| Above code block prints 8 char string of base64 encoded big-endian
| bytes of 32 bit CRC32c integer.
|
| More details on CRC32c can be found in Appendix B:
| https://datatracker.ietf.org/doc/html/rfc4960#appendix-B and
| base64: https://datatracker.ietf.org/doc/html/rfc4648#section-4
|
| :raises: :class:`~google.cloud.exceptions.GoogleCloudError`
| if the upload response returns an error status.
|
| upload_from_filename(self, filename, content_type=None, client=None, predefined_acl=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='auto', retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, crc32c_checksum_value=None)
| Upload this blob's contents from the content of a named file.
|
| The content type of the upload will be determined in order
| of precedence:
|
| - The value passed in to this method (if not :data:`None`)
| - The value stored on the current blob
| - The value given by ``mimetypes.guess_type``
| - The default value ('application/octet-stream')
|
| .. note::
| The effect of uploading to an existing blob depends on the
| "versioning" and "lifecycle" policies defined on the blob's
| bucket. In the absence of those policies, upload will
| overwrite any existing contents.
|
| See the [`object versioning`](https://cloud.google.com/storage/docs/object-versioning)
| and [`lifecycle`](https://cloud.google.com/storage/docs/lifecycle)
| API documents for details.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| See a [code sample](https://cloud.google.com/storage/docs/samples/storage-upload-encrypted-file#storage_upload_encrypted_file-python)
| to upload a file with a
| [`customer-supplied encryption key`](https://cloud.google.com/storage/docs/encryption#customer-supplied).
|
| :type filename: str
| :param filename: The path to the file.
|
| :type content_type: str
| :param content_type: (Optional) Type of content being uploaded.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type predefined_acl: str
| :param predefined_acl: (Optional) Predefined access control list
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type checksum: str
| :param checksum:
| (Optional) The type of checksum to compute to verify
| the integrity of the object. If the upload is completed in a single
| request, the checksum will be entirely precomputed and the remote
| server will handle verification and error handling. If the upload
| is too large and must be transmitted in multiple requests, the
| checksum will be incrementally computed and the client will handle
| verification and error handling, raising
| google.cloud.storage.exceptions.DataCorruption on a mismatch and
| attempting to delete the corrupted file. 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.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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_generation_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 crc32c_checksum_value: str
| :param crc32c_checksum_value: (Optional) This should be the checksum of
| the entire contents of `filename`. Applicable while uploading object
| greater than `_MAX_MULTIPART_SIZE` bytes.
|
| It can be obtained by running
|
| `gcloud storage hash /path/to/your/file`
|
| or
|
| .. code-block:: python
|
| import google_crc32c
| import base64
|
| data = b"Hello, world!"
| crc32c_int = google_crc32c.value(data)
| crc32c_hex = f"{crc32c_int:08x}"
| crc32c_bytes = crc32c_int.to_bytes(4, "big")
| base64_encoded = base64.b64encode(crc32c_bytes)
| crc32c_base64 = base64_encoded.decode("utf-8")
|
| print(crc32c_base64)
|
| Above code block prints 8 char string of base64 encoded big-endian
| bytes of 32 bit CRC32c integer.
|
| More details on CRC32c can be found in Appendix B:
| https://datatracker.ietf.org/doc/html/rfc4960#appendix-B and
| base64: https://datatracker.ietf.org/doc/html/rfc4648#section-4
|
| upload_from_string(self, data, content_type='text/plain', client=None, predefined_acl=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='auto', retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, crc32c_checksum_value=None)
| Upload contents of this blob from the provided string.
|
| .. note::
| The effect of uploading to an existing blob depends on the
| "versioning" and "lifecycle" policies defined on the blob's
| bucket. In the absence of those policies, upload will
| overwrite any existing contents.
|
| See the [`object versioning`](https://cloud.google.com/storage/docs/object-versioning)
| and [`lifecycle`](https://cloud.google.com/storage/docs/lifecycle)
| API documents for details.
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type data: bytes or str
| :param data:
| The data to store in this blob. If the value is text, it will be
| encoded as UTF-8.
|
| :type content_type: str
| :param content_type:
| (Optional) Type of content being uploaded. Defaults to
| ``'text/plain'``.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. If not passed, falls back to the
| ``client`` stored on the blob's bucket.
|
| :type predefined_acl: str
| :param predefined_acl: (Optional) Predefined access control list
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type checksum: str
| :param checksum:
| (Optional) The type of checksum to compute to verify
| the integrity of the object. If the upload is completed in a single
| request, the checksum will be entirely precomputed and the remote
| server will handle verification and error handling. If the upload
| is too large and must be transmitted in multiple requests, the
| checksum will be incrementally computed and the client will handle
| verification and error handling, raising
| google.cloud.storage.exceptions.DataCorruption on a mismatch and
| attempting to delete the corrupted file. 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.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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_generation_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 crc32c_checksum_value: str
| :param crc32c_checksum_value: (Optional) This should be the checksum of
| the entire contents of `file_obj`. Applicable while uploading object
| greater than `_MAX_MULTIPART_SIZE` bytes.
|
| It can be obtained by running
|
| `gcloud storage hash /path/to/your/file`
|
| or
|
| .. code-block:: python
|
| import google_crc32c
| import base64
|
| data = b"Hello, world!"
| crc32c_int = google_crc32c.value(data)
| crc32c_hex = f"{crc32c_int:08x}"
| crc32c_bytes = crc32c_int.to_bytes(4, "big")
| base64_encoded = base64.b64encode(crc32c_bytes)
| crc32c_base64 = base64_encoded.decode("utf-8")
|
| print(crc32c_base64)
|
| Above code block prints 8 char string of base64 encoded big-endian
| bytes of 32 bit CRC32c integer.
|
| More details on CRC32c can be found in Appendix B:
| https://datatracker.ietf.org/doc/html/rfc4960#appendix-B and
| base64: https://datatracker.ietf.org/doc/html/rfc4648#section-4
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_string(uri, client=None)
| (Deprecated) Get a constructor for blob object by URI.
|
| .. note::
| Deprecated alias for :meth:`from_uri`.
|
| .. code-block:: python
|
| from google.cloud import storage
| from google.cloud.storage.blob import Blob
| client = storage.Client()
| blob = Blob.from_string("gs://bucket/object", client=client)
|
| :type uri: str
| :param uri: The blob uri following a gs://bucket/object pattern.
| Both a bucket and object name is required to construct a blob object.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. Application code should
| *always* pass ``client``.
|
| :rtype: :class:`google.cloud.storage.blob.Blob`
| :returns: The blob object created.
|
| from_uri(uri, client=None)
| Get a constructor for blob object by URI.
|
| .. code-block:: python
|
| from google.cloud import storage
| from google.cloud.storage.blob import Blob
| client = storage.Client()
| blob = Blob.from_uri("gs://bucket/object", client=client)
|
| :type uri: str
| :param uri: The blob uri following a gs://bucket/object pattern.
| Both a bucket and object name is required to construct a blob object.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client:
| (Optional) The client to use. Application code should
| *always* pass ``client``.
|
| :rtype: :class:`google.cloud.storage.blob.Blob`
| :returns: The blob object created.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| path_helper(bucket_path, blob_name)
| Relative URL path for a blob.
|
| :type bucket_path: str
| :param bucket_path: The URL path for a bucket.
|
| :type blob_name: str
| :param blob_name: The name of the blob.
|
| :rtype: str
| :returns: The relative URL path for ``blob_name``.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| acl
| Create our ACL on demand.
|
| bucket
| Bucket which contains the object.
|
| :rtype: :class:`~google.cloud.storage.bucket.Bucket`
| :returns: The object's bucket.
|
| client
| The client bound to this blob.
|
| component_count
| Number of underlying components that make up this object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: int or ``NoneType``
| :returns: The component count (in case of a composed object) or
| ``None`` if the blob's resource has not been loaded from
| the server. This property will not be set on objects
| not created via ``compose``.
|
| etag
| Retrieve the ETag for the object.
|
| See [`RFC 2616 (etags)`](https://tools.ietf.org/html/rfc2616#section-3.11) and
| [`API reference docs`](https://cloud.google.com/storage/docs/json_api/v1/objects).
|
| :rtype: str or ``NoneType``
| :returns: The blob etag or ``None`` if the blob's resource has not
| been loaded from the server.
|
| finalized_time
| If this object has been soft-deleted, returns the time at which it will be permanently deleted.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns:
| (readonly) The time that the object will be permanently deleted.
| Note this property is only set for soft-deleted objects.
|
| generation
| Retrieve the generation for the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: int or ``NoneType``
| :returns: The generation of the blob or ``None`` if the blob's
| resource has not been loaded from the server.
|
| hard_delete_time
| If this object has been soft-deleted, returns the time at which it will be permanently deleted.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns:
| (readonly) The time that the object will be permanently deleted.
| Note this property is only set for soft-deleted objects.
|
| id
| Retrieve the ID for the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| The ID consists of the bucket name, object name, and generation number.
|
| :rtype: str or ``NoneType``
| :returns: The ID of the blob or ``None`` if the blob's
| resource has not been loaded from the server.
|
| media_link
| Retrieve the media download URI for the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: str or ``NoneType``
| :returns: The media link for the blob or ``None`` if the blob's
| resource has not been loaded from the server.
|
| metageneration
| Retrieve the metageneration for the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: int or ``NoneType``
| :returns: The metageneration of the blob or ``None`` if the blob's
| resource has not been loaded from the server.
|
| owner
| Retrieve info about the owner of the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: dict or ``NoneType``
| :returns: Mapping of owner's role/ID, or ``None`` if the blob's
| resource has not been loaded from the server.
|
| path
| Getter property for the URL path to this Blob.
|
| :rtype: str
| :returns: The URL path to this Blob.
|
| public_url
| The public URL for this blob.
|
| Use :meth:`make_public` to enable anonymous access via the returned
| URL.
|
| :rtype: `string`
| :returns: The public URL for this blob.
|
| retention
| Retrieve the retention configuration for this object.
|
| :rtype: :class:`Retention`
| :returns: an instance for managing the object's retention configuration.
|
| retention_expiration_time
| Retrieve timestamp at which the object's retention period expires.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the property is not set locally.
|
| self_link
| Retrieve the URI for the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: str or ``NoneType``
| :returns: The self link for the blob or ``None`` if the blob's
| resource has not been loaded from the server.
|
| size
| Size of the object, in bytes.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: int or ``NoneType``
| :returns: The size of the blob or ``None`` if the blob's
| resource has not been loaded from the server.
|
| soft_delete_time
| If this object has been soft-deleted, returns the time at which it became soft-deleted.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns:
| (readonly) The time that the object became soft-deleted.
| Note this property is only set for soft-deleted objects.
|
| time_created
| Retrieve the timestamp at which the object was created.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the blob's resource has not been loaded from
| the server (see :meth:`reload`).
|
| time_deleted
| Retrieve the timestamp at which the object was deleted.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the blob's resource has not been loaded from
| the server (see :meth:`reload`). If the blob has
| not been deleted, this will never be set.
|
| updated
| Retrieve the timestamp at which the object was updated.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the blob's resource has not been loaded from
| the server (see :meth:`reload`).
|
| user_project
| Project ID billed for API requests made via this blob.
|
| Derived from bucket's value.
|
| :rtype: str
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| cache_control
| Scalar property getter.
|
| chunk_size
| Get the blob's default chunk size.
|
| :rtype: int or ``NoneType``
| :returns: The current blob's chunk size, if it is set.
|
| content_disposition
| Scalar property getter.
|
| content_encoding
| Scalar property getter.
|
| content_language
| Scalar property getter.
|
| content_type
| Scalar property getter.
|
| contexts
| Retrieve the contexts for this object.
|
| :rtype: :class:`ObjectContexts`
| :returns: an instance for managing the object's contexts.
|
| crc32c
| Scalar property getter.
|
| custom_time
| Retrieve the custom time for the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the blob's resource has not been loaded from
| the server (see :meth:`reload`).
|
| encryption_key
| Retrieve the customer-supplied encryption key for the object.
|
| :rtype: bytes or ``NoneType``
| :returns:
| The encryption key or ``None`` if no customer-supplied encryption key was used,
| or the blob's resource has not been loaded from the server.
|
| event_based_hold
| Scalar property getter.
|
| kms_key_name
| Resource name of Cloud KMS key used to encrypt the blob's contents.
|
| :rtype: str or ``NoneType``
| :returns:
| The resource name or ``None`` if no Cloud KMS key was used,
| or the blob's resource has not been loaded from the server.
|
| md5_hash
| Scalar property getter.
|
| metadata
| Retrieve arbitrary/application specific metadata for the object.
|
| See https://cloud.google.com/storage/docs/json_api/v1/objects
|
| :setter: Update arbitrary/application specific metadata for the
| object.
| :getter: Retrieve arbitrary/application specific metadata for
| the object.
|
| :rtype: dict or ``NoneType``
| :returns: The metadata associated with the blob or ``None`` if the
| property is not set.
|
| storage_class
| Scalar property getter.
|
| temporary_hold
| Scalar property getter.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| STORAGE_CLASSES = ('STANDARD', 'NEARLINE', 'COLDLINE', 'ARCHIVE', 'MUL...
|
| ----------------------------------------------------------------------
| Methods inherited from google.cloud.storage._helpers._PropertyMixin:
|
| patch(self, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, override_unlocked_retention=False)
| Sends all changed properties in a PATCH request.
|
| Updates the ``_properties`` with the response from the backend.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: the client to use. If not passed, falls back to the
| ``client`` stored on the current object.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type override_unlocked_retention: bool
| :param override_unlocked_retention:
| (Optional) override_unlocked_retention must be set to True if the operation includes
| a retention property that changes the mode from Unlocked to Locked, reduces the
| retainUntilTime, or removes the retention configuration from the object. See:
| https://cloud.google.com/storage/docs/json_api/v1/objects/patch
|
| reload(self, client=None, projection='noAcl', if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, soft_deleted=None)
| Reload properties from Cloud Storage.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: the client to use. If not passed, falls back to the
| ``client`` stored on the current object.
|
| :type projection: str
| :param projection: (Optional) If used, must be 'full' or 'noAcl'.
| Defaults to ``'noAcl'``. Specifies the set of
| properties to return.
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match: (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]])
| :param if_etag_not_match: (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type soft_deleted: bool
| :param soft_deleted:
| (Optional) If True, looks for a soft-deleted object. Will only return
| the object metadata if the object exists and is in a soft-deleted state.
| :attr:`generation` is required to be set on the blob if ``soft_deleted`` is set to True.
| See: https://cloud.google.com/storage/docs/soft-delete
|
| update(self, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>, override_unlocked_retention=False)
| Sends all properties in a PUT request.
|
| Updates the ``_properties`` with the response from the backend.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: the client to use. If not passed, falls back to the
| ``client`` stored on the current object.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type override_unlocked_retention: bool
| :param override_unlocked_retention:
| (Optional) override_unlocked_retention must be set to True if the operation includes
| a retention property that changes the mode from Unlocked to Locked, reduces the
| retainUntilTime, or removes the retention configuration from the object. See:
| https://cloud.google.com/storage/docs/json_api/v1/objects/patch
|
| ----------------------------------------------------------------------
| Data descriptors inherited from google.cloud.storage._helpers._PropertyMixin:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class ObjectContexts(builtins.dict)
| ObjectContexts(blob, custom=None)
|
| Container for an object's contexts.
|
| See: https://docs.cloud.google.com/storage/docs/object-contexts
|
| :type blob: :class:`Blob`
| :param blob: blob for which these contexts apply to.
|
| :type custom: dict or ``NoneType``
| :param custom: (Optional) Custom contexts mapping.
|
| Method resolution order:
| ObjectContexts
| builtins.dict
| builtins.object
|
| Methods defined here:
|
| __init__(self, blob, custom=None)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_api_repr(resource, blob)
| Factory: construct instance from resource.
|
| :type resource: dict
| :param resource: mapping as returned from API call.
|
| :type blob: :class:`Blob`
| :param blob: Blob for which these contexts apply to.
|
| :rtype: :class:`ObjectContexts`
| :returns: ObjectContexts instance created from resource.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| blob
| Blob for which these contexts apply to.
|
| :rtype: :class:`Blob`
| :returns: the instance's blob.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| custom
| Custom contexts mapping.
|
| :rtype: dict
| :returns: Mapping of keys to :class:`ObjectCustomContextPayload` instances.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class ObjectCustomContextPayload(builtins.dict)
| ObjectCustomContextPayload(value=None)
|
| Payload for a custom context.
|
| :type value: str or ``NoneType``
| :param value: (Optional) The value of the custom context.
|
| Method resolution order:
| ObjectCustomContextPayload
| builtins.dict
| builtins.object
|
| Methods defined here:
|
| __init__(self, value=None)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| create_time
| Creation time of the custom context.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp.
|
| update_time
| Last update time of the custom context.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| value
| The value of the custom context.
|
| :rtype: str or ``NoneType``
| :returns: The value of the custom context.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class Retention(builtins.dict)
| Retention(blob, mode=None, retain_until_time=None, retention_expiration_time=None)
|
| Map an object's retention configuration.
|
| :type blob: :class:`Blob`
| :params blob: blob for which this retention configuration applies to.
|
| :type mode: str or ``NoneType``
| :params mode:
| (Optional) The mode of the retention configuration, which can be either Unlocked or Locked.
| See: https://cloud.google.com/storage/docs/object-lock
|
| :type retain_until_time: :class:`datetime.datetime` or ``NoneType``
| :params retain_until_time:
| (Optional) The earliest time that the object can be deleted or replaced, which is the
| retention configuration set for this object.
|
| :type retention_expiration_time: :class:`datetime.datetime` or ``NoneType``
| :params retention_expiration_time:
| (Optional) The earliest time that the object can be deleted, which depends on any
| retention configuration set for the object and any retention policy set for the bucket
| that contains the object. This value should normally only be set by the back-end API.
|
| Method resolution order:
| Retention
| builtins.dict
| builtins.object
|
| Methods defined here:
|
| __init__(self, blob, mode=None, retain_until_time=None, retention_expiration_time=None)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_api_repr(resource, blob)
| Factory: construct instance from resource.
|
| :type blob: :class:`Blob`
| :params blob: Blob for which this retention configuration applies to.
|
| :type resource: dict
| :param resource: mapping as returned from API call.
|
| :rtype: :class:`Retention`
| :returns: Retention configuration created from resource.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| blob
| Blob for which this retention configuration applies to.
|
| :rtype: :class:`Blob`
| :returns: the instance's blob.
|
| retention_expiration_time
| The earliest time that the object can be deleted, which depends on any
| retention configuration set for the object and any retention policy set for
| the bucket that contains the object.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns:
| (readonly) The earliest time that the object can be deleted.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| mode
| The mode of the retention configuration. Options are 'Unlocked' or 'Locked'.
|
| :rtype: string
| :returns: The mode of the retention configuration, which can be either set to 'Unlocked' or 'Locked'.
|
| retain_until_time
| The earliest time that the object can be deleted or replaced, which is the
| retention configuration set for this object.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the blob's resource has not been loaded from
| the server (see :meth:`reload`).
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
DATA
ARCHIVE_STORAGE_CLASS = 'ARCHIVE'
COLDLINE_STORAGE_CLASS = 'COLDLINE'
DEFAULT_RETRY = <google.api_core.retry.retry_unary.Retry object>
DEFAULT_RETRY_IF_ETAG_IN_JSON = <google.cloud.storage.retry.Conditiona...
DEFAULT_RETRY_IF_GENERATION_SPECIFIED = <google.cloud.storage.retry.Co...
MULTI_REGIONAL_LEGACY_STORAGE_CLASS = 'MULTI_REGIONAL'
NEARLINE_STORAGE_CLASS = 'NEARLINE'
REGIONAL_LEGACY_STORAGE_CLASS = 'REGIONAL'
STANDARD_STORAGE_CLASS = 'STANDARD'
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\google\cloud\storage\blob.py
google-cloud-storage.bucket
Python Library Documentation: module google.cloud.storage.bucket in google.cloud.storage
NAME
google.cloud.storage.bucket - Create / interact with Google Cloud Storage buckets.
CLASSES
builtins.dict(builtins.object)
BucketEncryption
EncryptionEnforcementConfig
IAMConfiguration
LifecycleRuleAbortIncompleteMultipartUpload
LifecycleRuleConditions
LifecycleRuleDelete
LifecycleRuleSetStorageClass
SoftDeletePolicy
google.cloud.storage._helpers._PropertyMixin(builtins.object)
Bucket
class Bucket(google.cloud.storage._helpers._PropertyMixin)
| Bucket(client, name=None, user_project=None, generation=None)
|
| A class representing a Bucket on Cloud Storage.
|
| :type client: :class:`google.cloud.storage.client.Client`
| :param client: A client which holds credentials and project configuration
| for the bucket (which requires a project).
|
| :type name: str
| :param name: The name of the bucket. Bucket names must start and end with a
| number or letter.
|
| :type user_project: str
| :param user_project: (Optional) the project ID to be billed for API
| requests made via this instance.
|
| :type generation: int
| :param generation: (Optional) If present, selects a specific revision of
| this bucket.
|
| Method resolution order:
| Bucket
| google.cloud.storage._helpers._PropertyMixin
| builtins.object
|
| Methods defined here:
|
| __init__(self, client, name=None, user_project=None, generation=None)
| property :attr:`name`
| Get the bucket's name.
|
| __repr__(self)
| Return repr(self).
|
| add_lifecycle_abort_incomplete_multipart_upload_rule(self, **kw)
| Add a "abort incomplete multipart upload" rule to lifecycle rules.
|
| .. note::
| The "age" lifecycle condition is the only supported condition
| for this rule.
|
| This defines a [lifecycle configuration](https://cloud.google.com/storage/docs/lifecycle),
| which is set on the bucket. For the general format of a lifecycle configuration, see the
| [bucket resource representation for JSON](https://cloud.google.com/storage/docs/json_api/v1/buckets).
|
| :type kw: dict
| :params kw: arguments passed to :class:`LifecycleRuleConditions`.
|
| add_lifecycle_delete_rule(self, **kw)
| Add a "delete" rule to lifecycle rules configured for this bucket.
|
| This defines a [lifecycle configuration](https://cloud.google.com/storage/docs/lifecycle),
| which is set on the bucket. For the general format of a lifecycle configuration, see the
| [bucket resource representation for JSON](https://cloud.google.com/storage/docs/json_api/v1/buckets).
| See also a [code sample](https://cloud.google.com/storage/docs/samples/storage-enable-bucket-lifecycle-management#storage_enable_bucket_lifecycle_management-python).
|
| :type kw: dict
| :params kw: arguments passed to :class:`LifecycleRuleConditions`.
|
| add_lifecycle_set_storage_class_rule(self, storage_class, **kw)
| Add a "set storage class" rule to lifecycle rules.
|
| This defines a [lifecycle configuration](https://cloud.google.com/storage/docs/lifecycle),
| which is set on the bucket. For the general format of a lifecycle configuration, see the
| [bucket resource representation for JSON](https://cloud.google.com/storage/docs/json_api/v1/buckets).
|
| :type storage_class: str, one of :attr:`STORAGE_CLASSES`.
| :param storage_class: new storage class to assign to matching items.
|
| :type kw: dict
| :params kw: arguments passed to :class:`LifecycleRuleConditions`.
|
| blob(self, blob_name, chunk_size=None, encryption_key=None, kms_key_name=None, generation=None)
| Factory constructor for blob object.
|
| .. note::
| This will not make an HTTP request; it simply instantiates
| a blob object owned by this bucket.
|
| :type blob_name: str
| :param blob_name: The name of the blob to be instantiated.
|
| :type chunk_size: int
| :param chunk_size: The size of a chunk of data whenever iterating
| (in bytes). This must be a multiple of 256 KB per
| the API specification.
|
| :type encryption_key: bytes
| :param encryption_key:
| (Optional) 32 byte encryption key for customer-supplied encryption.
|
| :type kms_key_name: str
| :param kms_key_name:
| (Optional) Resource name of KMS key used to encrypt blob's content.
|
| :type generation: long
| :param generation: (Optional) If present, selects a specific revision of
| this object.
|
| :type crc32c_checksum: str
| :param crc32c_checksum:
| (Optional) If set, the CRC32C checksum of the blob's content.
| CRC32c checksum, as described in RFC 4960, Appendix B; encoded using
| base64 in big-endian byte order. See
| Apenndix B: https://datatracker.ietf.org/doc/html/rfc4960#appendix-B
| base64: https://datatracker.ietf.org/doc/html/rfc4648#section-4
|
| :rtype: :class:`google.cloud.storage.blob.Blob`
| :returns: The blob object created.
|
| clear_lifecycle_rules(self)
| Clear lifecycle rules configured for this bucket.
|
| See https://cloud.google.com/storage/docs/lifecycle and
| https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| clear_lifecyle_rules(self)
| Deprecated alias for clear_lifecycle_rules.
|
| configure_website(self, main_page_suffix=None, not_found_page=None)
| Configure website-related properties.
|
| See https://cloud.google.com/storage/docs/static-website
|
| .. note::
| This configures the bucket's website-related properties,controlling how
| the service behaves when accessing bucket contents as a web site.
| See [tutorials](https://cloud.google.com/storage/docs/hosting-static-website) and
| [code samples](https://cloud.google.com/storage/docs/samples/storage-define-bucket-website-configuration#storage_define_bucket_website_configuration-python)
| for more information.
|
| :type main_page_suffix: str
| :param main_page_suffix: The page to use as the main page
| of a directory.
| Typically something like index.html.
|
| :type not_found_page: str
| :param not_found_page: The file to use when a page isn't found.
|
| copy_blob(self, blob, destination_bucket, new_name=None, client=None, preserve_acl=True, source_generation=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, if_source_generation_match=None, if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2CF29F40>, destination_contexts=None)
| Copy the given blob to the given bucket, optionally with a new name.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/objects/copy)
| and a [code sample](https://cloud.google.com/storage/docs/samples/storage-copy-file#storage_copy_file-python).
|
| :type blob: :class:`google.cloud.storage.blob.Blob`
| :param blob: The blob to be copied.
|
| :type destination_bucket: :class:`google.cloud.storage.bucket.Bucket`
| :param destination_bucket: The bucket into which the blob should be
| copied.
|
| :type new_name: str
| :param new_name: (Optional) The new name for the copied file.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type preserve_acl: bool
| :param preserve_acl: DEPRECATED. This argument is not functional!
| (Optional) Copies ACL from old blob to new blob.
| Default: True.
| Note that ``preserve_acl`` is not supported in a
| ``Batch`` context.
|
| :type source_generation: long
| :param source_generation: (Optional) The generation of the blob to be
| copied.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_source_generation_match: long
| :param if_source_generation_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation matches the given value.
|
| :type if_source_generation_not_match: long
| :param if_source_generation_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation does not match the given value.
|
| :type if_source_metageneration_match: long
| :param if_source_metageneration_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration matches the given value.
|
| :type if_source_metageneration_not_match: long
| :param if_source_metageneration_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration does not match the given value.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC.
| The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
| policy which will only enable retries if ``if_generation_match`` or ``generation``
| is set, in order to ensure requests are idempotent before retrying them.
| Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
| to enable retries regardless of generation precondition setting.
| See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| :type destination_contexts: :class:`~google.cloud.storage.blob.ObjectContexts` or dict
| :param destination_contexts:
| (Optional) New contexts to set for the destination object.
| See: https://docs.cloud.google.com/storage/docs/use-object-contexts#manage_object_contexts_during_object_operations
| :rtype: :class:`google.cloud.storage.blob.Blob`
| :returns: The new Blob.
|
| create(self, client=None, project=None, location=None, predefined_acl=None, predefined_default_object_acl=None, enable_object_retention=False, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Creates current bucket.
|
| If the bucket already exists, will raise
| :class:`google.cloud.exceptions.Conflict`.
|
| This implements "storage.buckets.insert".
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type project: str
| :param project: (Optional) The project under which the bucket is to
| be created. If not passed, uses the project set on
| the client.
| :raises ValueError: if ``project`` is None and client's
| :attr:`project` is also None.
|
| :type location: str
| :param location: (Optional) The location of the bucket. If not passed,
| the default location, US, will be used. See
| https://cloud.google.com/storage/docs/bucket-locations
|
| :type predefined_acl: str
| :param predefined_acl:
| (Optional) Name of predefined ACL to apply to bucket. See:
| https://cloud.google.com/storage/docs/access-control/lists#predefined-acl
|
| :type predefined_default_object_acl: str
| :param predefined_default_object_acl:
| (Optional) Name of predefined ACL to apply to bucket's objects. See:
| https://cloud.google.com/storage/docs/access-control/lists#predefined-acl
|
| :type enable_object_retention: bool
| :param enable_object_retention:
| (Optional) Whether object retention should be enabled on this bucket. See:
| https://cloud.google.com/storage/docs/object-lock
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| delete(self, force=False, client=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Delete this bucket.
|
| The bucket **must** be empty in order to submit a delete request. If
| ``force=True`` is passed, this will first attempt to delete all the
| objects / blobs in the bucket (i.e. try to empty the bucket).
|
| If the bucket doesn't exist, this will raise
| :class:`google.cloud.exceptions.NotFound`. If the bucket is not empty
| (and ``force=False``), will raise :class:`google.cloud.exceptions.Conflict`.
|
| If ``force=True`` and the bucket contains more than 256 objects / blobs
| this will cowardly refuse to delete the objects (or the bucket). This
| is to prevent accidental bucket deletion and to prevent extremely long
| runtime of this method. Also note that ``force=True`` is not supported
| in a ``Batch`` context.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type force: bool
| :param force: If True, empties the bucket's objects then deletes it.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration matches the given value.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration does not match the given value.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :raises: :class:`ValueError` if ``force`` is ``True`` and the bucket
| contains more than 256 objects / blobs.
|
| delete_blob(self, blob_name, client=None, generation=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Deletes a blob from the current bucket.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type blob_name: str
| :param blob_name: A blob name to delete.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type generation: long
| :param generation: (Optional) If present, permanently deletes a specific
| revision of this object.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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_generation_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.
|
| :raises: :class:`google.cloud.exceptions.NotFound` Raises a NotFound
| if the blob isn't found. To suppress
| the exception, use :meth:`delete_blobs` by passing a no-op
| ``on_error`` callback.
|
| delete_blobs(self, blobs, on_error=None, client=None, preserve_generation=False, timeout=60, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Deletes a list of blobs from the current bucket.
|
| Uses :meth:`delete_blob` to delete each individual blob.
|
| By default, any generation information in the list of blobs is ignored, and the
| live versions of all blobs are deleted. Set `preserve_generation` to True
| if blob generation should instead be propagated from the list of blobs.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type blobs: list
| :param blobs: A list of :class:`~google.cloud.storage.blob.Blob`-s or
| blob names to delete.
|
| :type on_error: callable
| :param on_error: (Optional) Takes single argument: ``blob``.
| Called once for each blob raising
| :class:`~google.cloud.exceptions.NotFound`;
| otherwise, the exception is propagated.
| Note that ``on_error`` is not supported in a ``Batch`` context.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type preserve_generation: bool
| :param preserve_generation: (Optional) Deletes only the generation specified on the blob object,
| instead of the live version, if set to True. Only :class:~google.cloud.storage.blob.Blob
| objects can have their generation set in this way.
| Default: False.
|
| :type if_generation_match: list of long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
| Note that the length of the list must match the length of
| The list must match ``blobs`` item-to-item.
|
| :type if_generation_not_match: list of long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
| The list must match ``blobs`` item-to-item.
|
| :type if_metageneration_match: list of long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
| The list must match ``blobs`` item-to-item.
|
| :type if_metageneration_not_match: list of long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
| The list must match ``blobs`` item-to-item.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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_generation_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.
|
| :raises: :class:`~google.cloud.exceptions.NotFound` (if
| `on_error` is not passed).
|
| disable_logging(self)
| Disable access logging for this bucket.
|
| See https://cloud.google.com/storage/docs/access-logs#disabling
|
| disable_website(self)
| Disable the website configuration for this bucket.
|
| This is really just a shortcut for setting the website-related
| attributes to ``None``.
|
| enable_logging(self, bucket_name, object_prefix='')
| Enable access logging for this bucket.
|
| See https://cloud.google.com/storage/docs/access-logs
|
| :type bucket_name: str
| :param bucket_name: name of bucket in which to store access logs
|
| :type object_prefix: str
| :param object_prefix: prefix for access log filenames
|
| exists(self, client=None, timeout=60, if_etag_match=None, if_etag_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Determines whether or not this bucket exists.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match: (Optional) Make the operation conditional on whether the
| bucket's current ETag matches the given value.
|
| :type if_etag_not_match: Union[str, Set[str]])
| :param if_etag_not_match: (Optional) Make the operation conditional on whether the
| bucket's current ETag does not match the given value.
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| bucket's current metageneration matches the given value.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| bucket's current metageneration does not match the given value.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: bool
| :returns: True if the bucket exists in Cloud Storage.
|
| generate_signed_url(self, expiration=None, api_access_endpoint=None, method='GET', headers=None, query_parameters=None, client=None, credentials=None, version=None, virtual_hosted_style=False, bucket_bound_hostname=None, scheme='http')
| Generates a signed URL for this bucket.
|
| .. note::
|
| If you are on Google Compute Engine, you can't generate a signed
| URL using GCE service account. If you'd like to be able to generate
| a signed URL from GCE, you can use a standard service account from a
| JSON file rather than a GCE service account.
|
| If you have a bucket that you want to allow access to for a set
| amount of time, you can use this method to generate a URL that
| is only valid within a certain time period.
|
| If ``bucket_bound_hostname`` is set as an argument of :attr:`api_access_endpoint`,
| ``https`` works only if using a ``CDN``.
|
| :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
| :param expiration: Point in time when the signed URL should expire. If
| a ``datetime`` instance is passed without an explicit
| ``tzinfo`` set, it will be assumed to be ``UTC``.
|
| :type api_access_endpoint: str
| :param api_access_endpoint: (Optional) URI base, for instance
| "https://storage.googleapis.com". If not specified, the client's
| api_endpoint will be used. Incompatible with bucket_bound_hostname.
|
| :type method: str
| :param method: The HTTP verb that will be used when requesting the URL.
|
| :type headers: dict
| :param headers:
| (Optional) Additional HTTP headers to be included as part of the
| signed URLs. See:
| https://cloud.google.com/storage/docs/xml-api/reference-headers
| Requests using the signed URL *must* pass the specified header
| (name and value) with each request for the URL.
|
| :type query_parameters: dict
| :param query_parameters:
| (Optional) Additional query parameters to be included as part of the
| signed URLs. See:
| https://cloud.google.com/storage/docs/xml-api/reference-headers#query
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the blob's bucket.
|
| :type credentials: :class:`google.auth.credentials.Credentials` or
| :class:`NoneType`
| :param credentials: The authorization credentials to attach to requests.
| These credentials identify this application to the service.
| If none are specified, the client will attempt to ascertain
| the credentials from the environment.
|
| :type version: str
| :param version: (Optional) The version of signed credential to create.
| Must be one of 'v2' | 'v4'.
|
| :type virtual_hosted_style: bool
| :param virtual_hosted_style:
| (Optional) If true, then construct the URL relative the bucket's
| virtual hostname, e.g., '<bucket-name>.storage.googleapis.com'.
| Incompatible with bucket_bound_hostname.
|
| :type bucket_bound_hostname: str
| :param bucket_bound_hostname:
| (Optional) If passed, then construct the URL relative to the bucket-bound hostname.
| Value can be a bare or with scheme, e.g., 'example.com' or 'http://example.com'.
| Incompatible with api_access_endpoint and virtual_hosted_style.
| See: https://cloud.google.com/storage/docs/request-endpoints#cname
|
| :type scheme: str
| :param scheme:
| (Optional) If ``bucket_bound_hostname`` is passed as a bare hostname, use
| this value as the scheme. ``https`` will work only when using a CDN.
| Defaults to ``"http"``.
|
| :raises: :exc:`ValueError` when version is invalid or mutually exclusive arguments are used.
| :raises: :exc:`TypeError` when expiration is not a valid type.
| :raises: :exc:`AttributeError` if credentials is not an instance
| of :class:`google.auth.credentials.Signing`.
|
| :rtype: str
| :returns: A signed URL you can use to access the resource
| until expiration.
|
| generate_upload_policy(self, conditions, expiration=None, client=None)
| Create a signed upload policy for uploading objects.
|
| This method generates and signs a policy document. You can use
| [`policy documents`](https://cloud.google.com/storage/docs/xml-api/post-object-forms)
| to allow visitors to a website to upload files to
| Google Cloud Storage without giving them direct write access.
| See a [code sample](https://cloud.google.com/storage/docs/xml-api/post-object-forms#python).
|
| :type expiration: datetime
| :param expiration: (Optional) Expiration in UTC. If not specified, the
| policy will expire in 1 hour.
|
| :type conditions: list
| :param conditions: A list of conditions as described in the
| `policy documents` documentation.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :rtype: dict
| :returns: A dictionary of (form field name, form field value) of form
| fields that should be added to your HTML upload form in order
| to attach the signature.
|
| get_blob(self, blob_name, client=None, encryption_key=None, generation=None, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, soft_deleted=None, **kwargs)
| Get a blob object by name.
|
| See a [code sample](https://cloud.google.com/storage/docs/samples/storage-get-metadata#storage_get_metadata-python)
| on how to retrieve metadata of an object.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type blob_name: str
| :param blob_name: The name of the blob to retrieve.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type encryption_key: bytes
| :param encryption_key:
| (Optional) 32 byte encryption key for customer-supplied encryption.
| See
| https://cloud.google.com/storage/docs/encryption#customer-supplied.
|
| :type generation: long
| :param generation:
| (Optional) If present, selects a specific revision of this object.
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match:
| (Optional) See :ref:`using-if-etag-match`
|
| :type if_etag_not_match: Union[str, Set[str]]
| :param if_etag_not_match:
| (Optional) See :ref:`using-if-etag-not-match`
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type soft_deleted: bool
| :param soft_deleted:
| (Optional) If True, looks for a soft-deleted object. Will only return
| the object metadata if the object exists and is in a soft-deleted state.
| Object ``generation`` is required if ``soft_deleted`` is set to True.
| See: https://cloud.google.com/storage/docs/soft-delete
|
| :param kwargs: Keyword arguments to pass to the
| :class:`~google.cloud.storage.blob.Blob` constructor.
|
| :rtype: :class:`google.cloud.storage.blob.Blob` or None
| :returns: The blob object if it exists, otherwise None.
|
| get_iam_policy(self, client=None, requested_policy_version=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Retrieve the IAM policy for the bucket.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/buckets/getIamPolicy)
| and a [code sample](https://cloud.google.com/storage/docs/samples/storage-view-bucket-iam-members#storage_view_bucket_iam_members-python).
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type requested_policy_version: int or ``NoneType``
| :param requested_policy_version: (Optional) The version of IAM policies to request.
| If a policy with a condition is requested without
| setting this, the server will return an error.
| This must be set to a value of 3 to retrieve IAM
| policies containing conditions. This is to prevent
| client code that isn't aware of IAM conditions from
| interpreting and modifying policies incorrectly.
| The service might return a policy with version lower
| than the one that was requested, based on the
| feature syntax in the policy fetched.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: :class:`google.api_core.iam.Policy`
| :returns: the policy instance, based on the resource returned from
| the ``getIamPolicy`` API request.
|
| get_logging(self)
| Return info about access logging for this bucket.
|
| See https://cloud.google.com/storage/docs/access-logs#status
|
| :rtype: dict or None
| :returns: a dict w/ keys, ``logBucket`` and ``logObjectPrefix``
| (if logging is enabled), or None (if not).
|
| get_notification(self, notification_id, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Get Pub / Sub notification for this bucket.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/notifications/get)
| and a [code sample](https://cloud.google.com/storage/docs/samples/storage-print-pubsub-bucket-notification#storage_print_pubsub_bucket_notification-python).
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type notification_id: str
| :param notification_id: The notification id to retrieve the notification configuration.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: :class:`.BucketNotification`
| :returns: notification instance.
|
| list_blobs(self, max_results=None, page_token=None, prefix=None, delimiter=None, start_offset=None, end_offset=None, include_trailing_delimiter=None, versions=None, projection='noAcl', fields=None, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, match_glob=None, include_folders_as_prefixes=None, soft_deleted=None, page_size=None, filter_=None)
| Return an iterator used to find blobs in the bucket.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type max_results: int
| :param max_results:
| (Optional) The maximum number of blobs to return.
|
| :type page_token: str
| :param page_token:
| (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.
|
| :type prefix: str
| :param prefix: (Optional) Prefix used to filter blobs.
|
| :type delimiter: str
| :param delimiter: (Optional) Delimiter, used with ``prefix`` to
| emulate hierarchy.
|
| :type start_offset: str
| :param start_offset:
| (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).
|
| :type end_offset: str
| :param end_offset:
| (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).
|
| :type include_trailing_delimiter: boolean
| :param include_trailing_delimiter:
| (Optional) If true, objects that end in exactly one instance of
| ``delimiter`` will have their metadata included in ``items`` in
| addition to ``prefixes``.
|
| :type versions: bool
| :param versions: (Optional) Whether object versions should be returned
| as separate blobs.
|
| :type projection: str
| :param projection: (Optional) If used, must be 'full' or 'noAcl'.
| Defaults to ``'noAcl'``. Specifies the set of
| properties to return.
|
| :type fields: str
| :param fields:
| (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
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type match_glob: str
| :param match_glob:
| (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
|
| :type 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
|
| :type soft_deleted: bool
| :param soft_deleted:
| (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
|
| :type filter_: str or None
| :param filter_:
| (Optional) Filter string used to filter objects. See:
| https://docs.cloud.google.com/storage/docs/listing-objects#filter-by-object-contexts-syntax
|
| :type page_size: int
| :param page_size:
| (Optional) Maximum number of blobs to return in each page.
| Defaults to a value set by the API.
|
| :rtype: :class:`~google.api_core.page_iterator.Iterator`
| :returns: Iterator of all :class:`~google.cloud.storage.blob.Blob`
| in this bucket matching the arguments.
|
| list_notifications(self, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| List Pub / Sub notifications for this bucket.
|
| See:
| https://cloud.google.com/storage/docs/json_api/v1/notifications/list
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: list of :class:`.BucketNotification`
| :returns: notification instances
|
| lock_retention_policy(self, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Lock the bucket's retention policy.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the blob's bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :raises ValueError:
| if the bucket has no metageneration (i.e., new or never reloaded);
| if the bucket has no retention policy assigned;
| if the bucket's retention policy is already locked.
|
| make_private(self, recursive=False, future=False, client=None, timeout=60, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Update bucket's ACL, revoking read access for anonymous users.
|
| :type recursive: bool
| :param recursive: If True, this will make all blobs inside the bucket
| private as well.
|
| :type future: bool
| :param future: If True, this will make all objects created in the
| future private as well.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration matches the given value.
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration does not match the given value.
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :raises ValueError:
| If ``recursive`` is True, and the bucket contains more than 256
| blobs. This is to prevent extremely long runtime of this
| method. For such buckets, iterate over the blobs returned by
| :meth:`list_blobs` and call
| :meth:`~google.cloud.storage.blob.Blob.make_private`
| for each blob.
|
| make_public(self, recursive=False, future=False, client=None, timeout=60, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Update bucket's ACL, granting read access to anonymous users.
|
| :type recursive: bool
| :param recursive: If True, this will make all blobs inside the bucket
| public as well.
|
| :type future: bool
| :param future: If True, this will make all objects created in the
| future public as well.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration matches the given value.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration does not match the given value.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :raises ValueError:
| If ``recursive`` is True, and the bucket contains more than 256
| blobs. This is to prevent extremely long runtime of this
| method. For such buckets, iterate over the blobs returned by
| :meth:`list_blobs` and call
| :meth:`~google.cloud.storage.blob.Blob.make_public`
| for each blob.
|
| move_blob(self, blob, new_name, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, if_source_generation_match=None, if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2CF29F40>)
| Move a blob to a new name atomically.
|
| If :attr:`user_project` is set on the bucket, bills the API request to that project.
|
| :type blob: :class:`google.cloud.storage.blob.Blob`
| :param blob: The blob to be renamed.
|
| :type new_name: str
| :param new_name: The new name for this blob.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type if_generation_match: int
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_generation_not_match: int
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_match: int
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_not_match: int
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_source_generation_match: int
| :param if_source_generation_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation matches the given value.
|
| :type if_source_generation_not_match: int
| :param if_source_generation_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation does not match the given value.
|
| :type if_source_metageneration_match: int
| :param if_source_metageneration_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration matches the given value.
|
| :type if_source_metageneration_not_match: int
| :param if_source_metageneration_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration does not match the given value.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry
| :param retry:
| (Optional) How to retry the RPC.
| See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| :rtype: :class:`Blob`
| :returns: The newly-moved blob.
|
| notification(self, topic_name=None, topic_project=None, custom_attributes=None, event_types=None, blob_name_prefix=None, payload_format='NONE', notification_id=None)
| Factory: create a notification resource for the bucket.
|
| See: :class:`.BucketNotification` for parameters.
|
| :rtype: :class:`.BucketNotification`
|
| patch(self, client=None, timeout=60, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Sends all changed properties in a PATCH request.
|
| Updates the ``_properties`` with the response from the backend.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: the client to use. If not passed, falls back to the
| ``client`` stored on the current object.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration matches the given value.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration does not match the given value.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| reload(self, client=None, projection='noAcl', timeout=60, if_etag_match=None, if_etag_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, soft_deleted=None)
| Reload properties from Cloud Storage.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: the client to use. If not passed, falls back to the
| ``client`` stored on the current object.
|
| :type projection: str
| :param projection: (Optional) If used, must be 'full' or 'noAcl'.
| Defaults to ``'noAcl'``. Specifies the set of
| properties to return.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_etag_match: Union[str, Set[str]]
| :param if_etag_match: (Optional) Make the operation conditional on whether the
| bucket's current ETag matches the given value.
|
| :type if_etag_not_match: Union[str, Set[str]])
| :param if_etag_not_match: (Optional) Make the operation conditional on whether the
| bucket's current ETag does not match the given value.
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| bucket's current metageneration matches the given value.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| bucket's current metageneration does not match the given value.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type soft_deleted: bool
| :param soft_deleted: (Optional) 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`` must be
| set if ``soft_deleted`` is set to True.
| See: https://cloud.google.com/storage/docs/soft-delete
|
| rename_blob(self, blob, new_name, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, if_source_generation_match=None, if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2CF29F40>)
| Rename the given blob using copy and delete operations.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| Effectively, copies blob to the same bucket with a new name, then
| deletes the blob.
|
| .. warning::
|
| This method will first duplicate the data and then delete the
| old blob. This means that with very large objects renaming
| could be a very (temporarily) costly or a very slow operation.
| If you need more control over the copy and deletion, instead
| use ``google.cloud.storage.blob.Blob.copy_to`` and
| ``google.cloud.storage.blob.Blob.delete`` directly.
|
| Also note that this method is not fully supported in a
| ``Batch`` context.
|
| :type blob: :class:`google.cloud.storage.blob.Blob`
| :param blob: The blob to be renamed.
|
| :type new_name: str
| :param new_name: The new name for this blob.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
| Note that the generation to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
| Note that the metageneration to be matched is that of the
| ``destination`` blob.
|
| :type if_source_generation_match: long
| :param if_source_generation_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation matches the given value. Also used in the
| (implied) delete request.
|
| :type if_source_generation_not_match: long
| :param if_source_generation_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's generation does not match the given value. Also used in
| the (implied) delete request.
|
| :type if_source_metageneration_match: long
| :param if_source_metageneration_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration matches the given value. Also used
| in the (implied) delete request.
|
| :type if_source_metageneration_not_match: long
| :param if_source_metageneration_not_match:
| (Optional) Makes the operation conditional on whether the source
| object's current metageneration does not match the given value.
| Also used in the (implied) delete request.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC.
| The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
| policy which will only enable retries if ``if_generation_match`` or ``generation``
| is set, in order to ensure requests are idempotent before retrying them.
| Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
| to enable retries regardless of generation precondition setting.
| See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| :rtype: :class:`Blob`
| :returns: The newly-renamed blob.
|
| restore_blob(self, blob_name, client=None, generation=None, copy_source_acl=None, projection=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2CF29F40>)
| Restores a soft-deleted object.
|
| If :attr:`user_project` is set on the bucket, bills the API request to that project.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/objects/restore)
|
| :type blob_name: str
| :param blob_name: The name of the blob to be restored.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type generation: int
| :param generation: Selects the specific revision of the object.
|
| :type copy_source_acl: bool
| :param copy_source_acl: (Optional) If true, copy the soft-deleted object's access controls.
|
| :type projection: str
| :param projection: (Optional) Specifies the set of properties to return.
| If used, must be 'full' or 'noAcl'.
|
| :type if_generation_match: long
| :param if_generation_match:
| (Optional) See :ref:`using-if-generation-match`
|
| :type if_generation_not_match: long
| :param if_generation_not_match:
| (Optional) See :ref:`using-if-generation-not-match`
|
| :type if_metageneration_match: long
| :param if_metageneration_match:
| (Optional) See :ref:`using-if-metageneration-match`
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match:
| (Optional) See :ref:`using-if-metageneration-not-match`
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC.
| The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, which
| only restore operations with ``if_generation_match`` or ``generation`` set
| will be retried.
|
| Users can configure non-default retry behavior. A ``None`` value will
| disable retries. A ``DEFAULT_RETRY`` value will enable retries
| even if restore operations are not guaranteed to be idempotent.
| See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| :rtype: :class:`google.cloud.storage.blob.Blob`
| :returns: The restored Blob.
|
| set_iam_policy(self, policy, client=None, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920980>)
| Update the IAM policy for the bucket.
|
| See
| https://cloud.google.com/storage/docs/json_api/v1/buckets/setIamPolicy
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type policy: :class:`google.api_core.iam.Policy`
| :param policy: policy instance used to update bucket's IAM policy.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: :class:`google.api_core.iam.Policy`
| :returns: the policy instance, based on the resource returned from
| the ``setIamPolicy`` API request.
|
| test_iam_permissions(self, permissions, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| API call: test permissions
|
| See
| https://cloud.google.com/storage/docs/json_api/v1/buckets/testIamPermissions
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type permissions: list of string
| :param permissions: the permissions to check
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: list of string
| :returns: the permissions returned by the ``testIamPermissions`` API
| request.
|
| update(self, client=None, timeout=60, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920950>)
| Sends all properties in a PUT request.
|
| Updates the ``_properties`` with the response from the backend.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: the client to use. If not passed, falls back to the
| ``client`` stored on the current object.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration matches the given value.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration does not match the given value.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_string(uri, client=None)
| Get a constructor for bucket object by URI.
|
| .. note::
| Deprecated alias for :meth:`from_uri`.
|
| .. code-block:: python
|
| from google.cloud import storage
| from google.cloud.storage.bucket import Bucket
| client = storage.Client()
| bucket = Bucket.from_string("gs://bucket", client=client)
|
| :type uri: str
| :param uri: The bucket uri pass to get bucket object.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. Application code should
| *always* pass ``client``.
|
| :rtype: :class:`google.cloud.storage.bucket.Bucket`
| :returns: The bucket object created.
|
| from_uri(uri, client=None)
| Get a constructor for bucket object by URI.
|
| .. code-block:: python
|
| from google.cloud import storage
| from google.cloud.storage.bucket import Bucket
| client = storage.Client()
| bucket = Bucket.from_uri("gs://bucket", client=client)
|
| :type uri: str
| :param uri: The bucket uri pass to get bucket object.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. Application code should
| *always* pass ``client``.
|
| :rtype: :class:`google.cloud.storage.bucket.Bucket`
| :returns: The bucket object created.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| path_helper(bucket_name)
| Relative URL path for a bucket.
|
| :type bucket_name: str
| :param bucket_name: The bucket name in the path.
|
| :rtype: str
| :returns: The relative URL path for ``bucket_name``.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| acl
| Create our ACL on demand.
|
| autoclass_terminal_storage_class_update_time
| The time at which the Autoclass terminal_storage_class field was last updated for this bucket
| :rtype: datetime.datetime or ``NoneType``
| :returns: point-in time at which the bucket's terminal_storage_class is last updated, or ``None`` if the property is not set locally.
|
| autoclass_toggle_time
| Retrieve the toggle time when Autoclaass was last enabled or disabled for the bucket.
| :rtype: datetime.datetime or ``NoneType``
| :returns: point-in time at which the bucket's autoclass is toggled, or ``None`` if the property is not set locally.
|
| client
| The client bound to this bucket.
|
| data_locations
| Retrieve the list of regional locations for custom dual-region buckets.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets and
| https://cloud.google.com/storage/docs/locations
|
| Returns ``None`` if the property has not been set before creation,
| if the bucket's resource has not been loaded from the server,
| or if the bucket is not a dual-regions bucket.
| :rtype: list of str or ``NoneType``
|
| default_object_acl
| Create our defaultObjectACL on demand.
|
| etag
| Retrieve the ETag for the bucket.
|
| See https://tools.ietf.org/html/rfc2616#section-3.11 and
| https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: str or ``NoneType``
| :returns: The bucket etag or ``None`` if the bucket's
| resource has not been loaded from the server.
|
| generation
| Retrieve the generation for the bucket.
|
| :rtype: int or ``NoneType``
| :returns: The generation of the bucket or ``None`` if the bucket's
| resource has not been loaded from the server.
|
| hard_delete_time
| If this bucket has been soft-deleted, returns the time at which it will be permanently deleted.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns:
| (readonly) The time that the bucket will be permanently deleted.
| Note this property is only set for soft-deleted buckets.
|
| iam_configuration
| Retrieve IAM configuration for this bucket.
|
| :rtype: :class:`IAMConfiguration`
| :returns: an instance for managing the bucket's IAM configuration.
|
| id
| Retrieve the ID for the bucket.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: str or ``NoneType``
| :returns: The ID of the bucket or ``None`` if the bucket's
| resource has not been loaded from the server.
|
| location_type
| Retrieve the location type for the bucket.
|
| See https://cloud.google.com/storage/docs/storage-classes
|
| :getter: Gets the the location type for this bucket.
|
| :rtype: str or ``NoneType``
| :returns:
| If set, one of
| :attr:`~google.cloud.storage.constants.MULTI_REGION_LOCATION_TYPE`,
| :attr:`~google.cloud.storage.constants.REGION_LOCATION_TYPE`, or
| :attr:`~google.cloud.storage.constants.DUAL_REGION_LOCATION_TYPE`,
| else ``None``.
|
| metageneration
| Retrieve the metageneration for the bucket.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: int or ``NoneType``
| :returns: The metageneration of the bucket or ``None`` if the bucket's
| resource has not been loaded from the server.
|
| object_retention_mode
| Retrieve the object retention mode set on the bucket.
|
| :rtype: str
| :returns: When set to Enabled, retention configurations can be
| set on objects in the bucket.
|
| owner
| Retrieve info about the owner of the bucket.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: dict or ``NoneType``
| :returns: Mapping of owner's role/ID. Returns ``None`` if the bucket's
| resource has not been loaded from the server.
|
| path
| The URL path to this bucket.
|
| project_number
| Retrieve the number of the project to which the bucket is assigned.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: int or ``NoneType``
| :returns: The project number that owns the bucket or ``None`` if
| the bucket's resource has not been loaded from the server.
|
| retention_policy_effective_time
| Retrieve the effective time of the bucket's retention policy.
|
| :rtype: datetime.datetime or ``NoneType``
| :returns: point-in time at which the bucket's retention policy is
| effective, or ``None`` if the property is not
| set locally.
|
| retention_policy_locked
| Retrieve whthere the bucket's retention policy is locked.
|
| :rtype: bool
| :returns: True if the bucket's policy is locked, or else False
| if the policy is not locked, or the property is not
| set locally.
|
| self_link
| Retrieve the URI for the bucket.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: str or ``NoneType``
| :returns: The self link for the bucket or ``None`` if
| the bucket's resource has not been loaded from the server.
|
| soft_delete_policy
| Retrieve the soft delete policy for this bucket.
|
| See https://cloud.google.com/storage/docs/soft-delete
|
| :rtype: :class:`SoftDeletePolicy`
| :returns: an instance for managing the bucket's soft delete policy.
|
| soft_delete_time
| If this bucket has been soft-deleted, returns the time at which it became soft-deleted.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns:
| (readonly) The time that the bucket became soft-deleted.
| Note this property is only set for soft-deleted buckets.
|
| time_created
| Retrieve the timestamp at which the bucket was created.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the bucket's resource has not been loaded
| from the server.
|
| updated
| Retrieve the timestamp at which the bucket was last updated.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the bucket's resource has not been loaded
| from the server.
|
| user_project
| Project ID to be billed for API requests made via this bucket.
|
| If unset, API requests are billed to the bucket owner.
|
| A user project is required for all operations on Requester Pays buckets.
|
| See https://cloud.google.com/storage/docs/requester-pays#requirements for details.
|
| :rtype: str
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| autoclass_enabled
| Whether Autoclass is enabled for this bucket.
|
| See https://cloud.google.com/storage/docs/using-autoclass for details.
|
| :setter: Update whether autoclass is enabled for this bucket.
| :getter: Query whether autoclass is enabled for this bucket.
|
| :rtype: bool
| :returns: True if enabled, else False.
|
| autoclass_terminal_storage_class
| The storage class that objects in an Autoclass bucket eventually transition to if
| they are not read for a certain length of time. Valid values are NEARLINE and ARCHIVE.
|
| See https://cloud.google.com/storage/docs/using-autoclass for details.
|
| :setter: Set the terminal storage class for Autoclass configuration.
| :getter: Get the terminal storage class for Autoclass configuration.
|
| :rtype: str
| :returns: The terminal storage class if Autoclass is enabled, else ``None``.
|
| cors
| Retrieve or set CORS policies configured for this bucket.
|
| See http://www.w3.org/TR/cors/ and
| https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| .. note::
|
| The getter for this property returns a list which contains
| *copies* of the bucket's CORS policy mappings. Mutating the list
| or one of its dicts has no effect unless you then re-assign the
| dict via the setter. E.g.:
|
| >>> policies = bucket.cors
| >>> policies.append({'origin': '/foo', ...})
| >>> policies[1]['maxAgeSeconds'] = 3600
| >>> del policies[0]
| >>> bucket.cors = policies
| >>> bucket.update()
|
| :setter: Set CORS policies for this bucket.
| :getter: Gets the CORS policies for this bucket.
|
| :rtype: list of dictionaries
| :returns: A sequence of mappings describing each CORS policy.
|
| default_event_based_hold
| Scalar property getter.
|
| default_kms_key_name
| Retrieve / set default KMS encryption key for objects in the bucket.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| :setter: Set default KMS encryption key for items in this bucket.
| :getter: Get default KMS encryption key for items in this bucket.
|
| :rtype: str
| :returns: Default KMS encryption key, or ``None`` if not set.
|
| encryption
| Retrieve encryption configuration for this bucket.
|
| :rtype: :class:`BucketEncryption`
| :returns: an instance for managing the bucket's encryption configuration.
|
| hierarchical_namespace_enabled
| Whether hierarchical namespace is enabled for this bucket.
|
| :setter: Update whether hierarchical namespace is enabled for this bucket.
| :getter: Query whether hierarchical namespace is enabled for this bucket.
|
| :rtype: bool
| :returns: True if enabled, else False.
|
| ip_filter
| Retrieve or set the IP Filter configuration for this bucket.
|
| See https://cloud.google.com/storage/docs/ip-filtering-overview and
| https://cloud.google.com/storage/docs/json_api/v1/buckets#ipFilter
|
| .. note::
| The getter for this property returns an
| :class:`~google.cloud.storage.ip_filter.IPFilter` object, which is a
| structured representation of the bucket's IP filter configuration.
| Modifying the returned object has no effect. To update the bucket's
| IP filter, create and assign a new ``IPFilter`` object to this
| property and then call
| :meth:`~google.cloud.storage.bucket.Bucket.patch`.
|
| .. code-block:: python
|
| from google.cloud.storage.ip_filter import (
| IPFilter,
| PublicNetworkSource,
| )
|
| ip_filter = IPFilter()
| ip_filter.mode = "Enabled"
| ip_filter.public_network_source = PublicNetworkSource(
| allowed_ip_cidr_ranges=["203.0.113.5/32"]
| )
| bucket.ip_filter = ip_filter
| bucket.patch()
|
| :setter: Set the IP Filter configuration for this bucket.
| :getter: Gets the IP Filter configuration for this bucket.
|
| :rtype: :class:`~google.cloud.storage.ip_filter.IPFilter` or ``NoneType``
| :returns:
| An ``IPFilter`` object representing the configuration, or ``None``
| if no filter is configured.
|
| labels
| Retrieve or set labels assigned to this bucket.
|
| See
| https://cloud.google.com/storage/docs/json_api/v1/buckets#labels
|
| .. note::
|
| The getter for this property returns a dict which is a *copy*
| of the bucket's labels. Mutating that dict has no effect unless
| you then re-assign the dict via the setter. E.g.:
|
| >>> labels = bucket.labels
| >>> labels['new_key'] = 'some-label'
| >>> del labels['old_key']
| >>> bucket.labels = labels
| >>> bucket.update()
|
| :setter: Set labels for this bucket.
| :getter: Gets the labels for this bucket.
|
| :rtype: :class:`dict`
| :returns: Name-value pairs (string->string) labelling the bucket.
|
| lifecycle_rules
| Retrieve or set lifecycle rules configured for this bucket.
|
| See https://cloud.google.com/storage/docs/lifecycle and
| https://cloud.google.com/storage/docs/json_api/v1/buckets
|
| .. note::
|
| The getter for this property returns a generator which yields
| *copies* of the bucket's lifecycle rules mappings. Mutating the
| output dicts has no effect unless you then re-assign the dict via
| the setter. E.g.:
|
| >>> rules = list(bucket.lifecycle_rules)
| >>> rules.append({'origin': '/foo', ...})
| >>> rules[1]['rule']['action']['type'] = 'Delete'
| >>> del rules[0]
| >>> bucket.lifecycle_rules = rules
| >>> bucket.update()
|
| :setter: Set lifecycle rules for this bucket.
| :getter: Gets the lifecycle rules for this bucket.
|
| :rtype: generator(dict)
| :returns: A sequence of mappings describing each lifecycle rule.
|
| location
| Retrieve location configured for this bucket.
|
| See https://cloud.google.com/storage/docs/json_api/v1/buckets and
| https://cloud.google.com/storage/docs/locations
|
| Returns ``None`` if the property has not been set before creation,
| or if the bucket's resource has not been loaded from the server.
| :rtype: str or ``NoneType``
|
| requester_pays
| Does the requester pay for API requests for this bucket?
|
| See https://cloud.google.com/storage/docs/requester-pays for
| details.
|
| :setter: Update whether requester pays for this bucket.
| :getter: Query whether requester pays for this bucket.
|
| :rtype: bool
| :returns: True if requester pays for API requests for the bucket,
| else False.
|
| retention_period
| Retrieve or set the retention period for items in the bucket.
|
| :rtype: int or ``NoneType``
| :returns: number of seconds to retain items after upload or release
| from event-based lock, or ``None`` if the property is not
| set locally.
|
| rpo
| Get the RPO (Recovery Point Objective) of this bucket
|
| See: https://cloud.google.com/storage/docs/managing-turbo-replication
|
| "ASYNC_TURBO" or "DEFAULT"
| :rtype: str
|
| storage_class
| Retrieve or set the storage class for the bucket.
|
| See https://cloud.google.com/storage/docs/storage-classes
|
| :setter: Set the storage class for this bucket.
| :getter: Gets the the storage class for this bucket.
|
| :rtype: str or ``NoneType``
| :returns:
| If set, one of
| :attr:`~google.cloud.storage.constants.NEARLINE_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.COLDLINE_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.ARCHIVE_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.STANDARD_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.MULTI_REGIONAL_LEGACY_STORAGE_CLASS`,
| :attr:`~google.cloud.storage.constants.REGIONAL_LEGACY_STORAGE_CLASS`,
| or
| :attr:`~google.cloud.storage.constants.DURABLE_REDUCED_AVAILABILITY_LEGACY_STORAGE_CLASS`,
| else ``None``.
|
| versioning_enabled
| Is versioning enabled for this bucket?
|
| See https://cloud.google.com/storage/docs/object-versioning for
| details.
|
| :setter: Update whether versioning is enabled for this bucket.
| :getter: Query whether versioning is enabled for this bucket.
|
| :rtype: bool
| :returns: True if enabled, else False.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| STORAGE_CLASSES = ('STANDARD', 'NEARLINE', 'COLDLINE', 'ARCHIVE', 'MUL...
|
| ----------------------------------------------------------------------
| Data descriptors inherited from google.cloud.storage._helpers._PropertyMixin:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class BucketEncryption(builtins.dict)
| BucketEncryption(bucket, default_kms_key_name=None, google_managed_encryption_enforcement_config=None, customer_managed_encryption_enforcement_config=None, customer_supplied_encryption_enforcement_config=None)
|
| Map a bucket's encryption configuration.
|
| :type bucket: :class:`Bucket`
| :param bucket: Bucket for which this instance is the policy.
|
| :type default_kms_key_name: str
| :param default_kms_key_name:
| (Optional) Resource name of KMS key used to encrypt bucket's content.
|
| :type google_managed_encryption_enforcement_config: :class:`EncryptionEnforcementConfig`
| :param google_managed_encryption_enforcement_config:
| (Optional) Encryption enforcement configuration for Google managed encryption.
|
| :type customer_managed_encryption_enforcement_config: :class:`EncryptionEnforcementConfig`
| :param customer_managed_encryption_enforcement_config:
| (Optional) Encryption enforcement configuration for Customer managed encryption.
|
| :type customer_supplied_encryption_enforcement_config: :class:`EncryptionEnforcementConfig`
| :param customer_supplied_encryption_enforcement_config:
| (Optional) Encryption enforcement configuration for Customer supplied encryption.
|
| Method resolution order:
| BucketEncryption
| builtins.dict
| builtins.object
|
| Methods defined here:
|
| __init__(self, bucket, default_kms_key_name=None, google_managed_encryption_enforcement_config=None, customer_managed_encryption_enforcement_config=None, customer_supplied_encryption_enforcement_config=None)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_api_repr(resource, bucket)
| Factory: construct instance from resource.
|
| :type resource: dict
| :param resource: mapping as returned from API call.
|
| :type bucket: :class:`Bucket`
| :params bucket: Bucket for which this instance is the policy.
|
| :rtype: :class:`BucketEncryption`
| :returns: Instance created from resource.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| bucket
| Bucket for which this instance is the policy.
|
| :rtype: :class:`Bucket`
| :returns: the instance's bucket.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| customer_managed_encryption_enforcement_config
| Retrieve the encryption enforcement configuration for Customer managed encryption.
|
| :rtype: :class:`EncryptionEnforcementConfig`
| :returns: The configuration instance.
|
| customer_supplied_encryption_enforcement_config
| Retrieve the encryption enforcement configuration for Customer supplied encryption.
|
| :rtype: :class:`EncryptionEnforcementConfig`
| :returns: The configuration instance.
|
| default_kms_key_name
| Retrieve default KMS encryption key for objects in the bucket.
|
| :rtype: str or ``NoneType``
| :returns: Default KMS encryption key, or ``None`` if not set.
|
| google_managed_encryption_enforcement_config
| Retrieve the encryption enforcement configuration for Google managed encryption.
|
| :rtype: :class:`EncryptionEnforcementConfig`
| :returns: The configuration instance.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class EncryptionEnforcementConfig(builtins.dict)
| EncryptionEnforcementConfig(restriction_mode=None)
|
| Map a bucket's encryption enforcement configuration.
|
| :type restriction_mode: str
| :param restriction_mode:
| (Optional) The restriction mode for the encryption type.
| When set to ``FullyRestricted``, the bucket will only allow objects encrypted with the encryption type corresponding to this configuration.
| When set to ``NotRestricted``, the bucket will allow objects encrypted with any encryption type.
|
| :type effective_time: :class:`datetime.datetime`
| :param effective_time:
| (Output only) The time when the encryption enforcement configuration became effective.
|
| Method resolution order:
| EncryptionEnforcementConfig
| builtins.dict
| builtins.object
|
| Methods defined here:
|
| __init__(self, restriction_mode=None)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_api_repr(resource)
| Factory: construct instance from resource.
|
| :type resource: dict
| :param resource: mapping as returned from API call.
|
| :rtype: :class:`EncryptionEnforcementConfig`
| :returns: Instance created from resource.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| effective_time
| Get the effective time.
|
| :rtype: datetime.datetime or ``NoneType``
| :returns: point-in time at which the configuration is effective,
| or ``None`` if the property is not set.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| restriction_mode
| Get the restriction mode.
|
| :rtype: str or ``NoneType``
| :returns: The restriction mode or ``None`` if the property is not set.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class IAMConfiguration(builtins.dict)
| IAMConfiguration(bucket, public_access_prevention=<object object at 0x0000022E2C0196B0>, uniform_bucket_level_access_enabled=<object object at 0x0000022E2C0196B0>, uniform_bucket_level_access_locked_time=<object object at 0x0000022E2C0196B0>, bucket_policy_only_enabled=<object object at 0x0000022E2C0196B0>, bucket_policy_only_locked_time=<object object at 0x0000022E2C0196B0>)
|
| Map a bucket's IAM configuration.
|
| :type bucket: :class:`Bucket`
| :params bucket: Bucket for which this instance is the policy.
|
| :type public_access_prevention: str
| :params public_access_prevention:
| (Optional) Whether the public access prevention policy is 'inherited' (default) or 'enforced'
| See: https://cloud.google.com/storage/docs/public-access-prevention
|
| :type uniform_bucket_level_access_enabled: bool
| :params bucket_policy_only_enabled:
| (Optional) Whether the IAM-only policy is enabled for the bucket.
|
| :type uniform_bucket_level_access_locked_time: :class:`datetime.datetime`
| :params uniform_bucket_level_locked_time:
| (Optional) When the bucket's IAM-only policy was enabled.
| This value should normally only be set by the back-end API.
|
| :type bucket_policy_only_enabled: bool
| :params bucket_policy_only_enabled:
| Deprecated alias for :data:`uniform_bucket_level_access_enabled`.
|
| :type bucket_policy_only_locked_time: :class:`datetime.datetime`
| :params bucket_policy_only_locked_time:
| Deprecated alias for :data:`uniform_bucket_level_access_locked_time`.
|
| Method resolution order:
| IAMConfiguration
| builtins.dict
| builtins.object
|
| Methods defined here:
|
| __init__(self, bucket, public_access_prevention=<object object at 0x0000022E2C0196B0>, uniform_bucket_level_access_enabled=<object object at 0x0000022E2C0196B0>, uniform_bucket_level_access_locked_time=<object object at 0x0000022E2C0196B0>, bucket_policy_only_enabled=<object object at 0x0000022E2C0196B0>, bucket_policy_only_locked_time=<object object at 0x0000022E2C0196B0>)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_api_repr(resource, bucket)
| Factory: construct instance from resource.
|
| :type bucket: :class:`Bucket`
| :params bucket: Bucket for which this instance is the policy.
|
| :type resource: dict
| :param resource: mapping as returned from API call.
|
| :rtype: :class:`IAMConfiguration`
| :returns: Instance created from resource.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| bucket
| Bucket for which this instance is the policy.
|
| :rtype: :class:`Bucket`
| :returns: the instance's bucket.
|
| bucket_policy_only_locked_time
| Deprecated alias for :attr:`uniform_bucket_level_access_locked_time`.
|
| :rtype: Union[:class:`datetime.datetime`, None]
| :returns:
| (readonly) Time after which :attr:`bucket_policy_only_enabled` will
| be frozen as true.
|
| uniform_bucket_level_access_locked_time
| Deadline for changing :attr:`uniform_bucket_level_access_enabled` from true to false.
|
| If the bucket's :attr:`uniform_bucket_level_access_enabled` is true, this property
| is time time after which that setting becomes immutable.
|
| If the bucket's :attr:`uniform_bucket_level_access_enabled` is false, this property
| is ``None``.
|
| :rtype: Union[:class:`datetime.datetime`, None]
| :returns: (readonly) Time after which :attr:`uniform_bucket_level_access_enabled` will
| be frozen as true.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| bucket_policy_only_enabled
| Deprecated alias for :attr:`uniform_bucket_level_access_enabled`.
|
| :rtype: bool
| :returns: whether the bucket is configured to allow only IAM.
|
| public_access_prevention
| Setting for public access prevention policy. Options are 'inherited' (default) or 'enforced'.
|
| See: https://cloud.google.com/storage/docs/public-access-prevention
|
| :rtype: string
| :returns: the public access prevention status, either 'enforced' or 'inherited'.
|
| uniform_bucket_level_access_enabled
| If set, access checks only use bucket-level IAM policies or above.
|
| :rtype: bool
| :returns: whether the bucket is configured to allow only IAM.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class LifecycleRuleAbortIncompleteMultipartUpload(builtins.dict)
| LifecycleRuleAbortIncompleteMultipartUpload(**kw)
|
| Map a rule aborting incomplete multipart uploads of matching items.
|
| The "age" lifecycle condition is the only supported condition for this rule.
|
| :type kw: dict
| :params kw: arguments passed to :class:`LifecycleRuleConditions`.
|
| Method resolution order:
| LifecycleRuleAbortIncompleteMultipartUpload
| builtins.dict
| builtins.object
|
| Methods defined here:
|
| __init__(self, **kw)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_api_repr(resource)
| Factory: construct instance from resource.
|
| :type resource: dict
| :param resource: mapping as returned from API call.
|
| :rtype: :class:`LifecycleRuleAbortIncompleteMultipartUpload`
| :returns: Instance created from resource.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class LifecycleRuleConditions(builtins.dict)
| LifecycleRuleConditions(age=None, created_before=None, is_live=None, matches_storage_class=None, number_of_newer_versions=None, days_since_custom_time=None, custom_time_before=None, days_since_noncurrent_time=None, noncurrent_time_before=None, matches_prefix=None, matches_suffix=None, _factory=False)
|
| Map a single lifecycle rule for a bucket.
|
| See: https://cloud.google.com/storage/docs/lifecycle
|
| :type age: int
| :param age: (Optional) Apply rule action to items whose age, in days,
| exceeds this value.
|
| :type created_before: datetime.date
| :param created_before: (Optional) Apply rule action to items created
| before this date.
|
| :type is_live: bool
| :param is_live: (Optional) If true, apply rule action to non-versioned
| items, or to items with no newer versions. If false, apply
| rule action to versioned items with at least one newer
| version.
|
| :type matches_prefix: list(str)
| :param matches_prefix: (Optional) Apply rule action to items which
| any prefix matches the beginning of the item name.
|
| :type matches_storage_class: list(str), one or more of
| :attr:`Bucket.STORAGE_CLASSES`.
| :param matches_storage_class: (Optional) Apply rule action to items
| whose storage class matches this value.
|
| :type matches_suffix: list(str)
| :param matches_suffix: (Optional) Apply rule action to items which
| any suffix matches the end of the item name.
|
| :type number_of_newer_versions: int
| :param number_of_newer_versions: (Optional) Apply rule action to versioned
| items having N newer versions.
|
| :type days_since_custom_time: int
| :param days_since_custom_time: (Optional) Apply rule action to items whose number of days
| elapsed since the custom timestamp. This condition is relevant
| only for versioned objects. The value of the field must be a non
| negative integer. If it's zero, the object version will become
| eligible for lifecycle action as soon as it becomes custom.
|
| :type custom_time_before: :class:`datetime.date`
| :param custom_time_before: (Optional) Date object parsed from RFC3339 valid date, apply rule action
| to items whose custom time is before this date. This condition is relevant
| only for versioned objects, e.g., 2019-03-16.
|
| :type days_since_noncurrent_time: int
| :param days_since_noncurrent_time: (Optional) Apply rule action to items whose number of days
| elapsed since the non current timestamp. This condition
| is relevant only for versioned objects. The value of the field
| must be a non negative integer. If it's zero, the object version
| will become eligible for lifecycle action as soon as it becomes
| non current.
|
| :type noncurrent_time_before: :class:`datetime.date`
| :param noncurrent_time_before: (Optional) Date object parsed from RFC3339 valid date, apply
| rule action to items whose non current time is before this date.
| This condition is relevant only for versioned objects, e.g, 2019-03-16.
|
| :raises ValueError: if no arguments are passed.
|
| Method resolution order:
| LifecycleRuleConditions
| builtins.dict
| builtins.object
|
| Methods defined here:
|
| __init__(self, age=None, created_before=None, is_live=None, matches_storage_class=None, number_of_newer_versions=None, days_since_custom_time=None, custom_time_before=None, days_since_noncurrent_time=None, noncurrent_time_before=None, matches_prefix=None, matches_suffix=None, _factory=False)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_api_repr(resource)
| Factory: construct instance from resource.
|
| :type resource: dict
| :param resource: mapping as returned from API call.
|
| :rtype: :class:`LifecycleRuleConditions`
| :returns: Instance created from resource.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| age
| Conditon's age value.
|
| created_before
| Conditon's created_before value.
|
| custom_time_before
| Conditon's 'custom_time_before' value.
|
| days_since_custom_time
| Conditon's 'days_since_custom_time' value.
|
| days_since_noncurrent_time
| Conditon's 'days_since_noncurrent_time' value.
|
| is_live
| Conditon's 'is_live' value.
|
| matches_prefix
| Conditon's 'matches_prefix' value.
|
| matches_storage_class
| Conditon's 'matches_storage_class' value.
|
| matches_suffix
| Conditon's 'matches_suffix' value.
|
| noncurrent_time_before
| Conditon's 'noncurrent_time_before' value.
|
| number_of_newer_versions
| Conditon's 'number_of_newer_versions' value.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class LifecycleRuleDelete(builtins.dict)
| LifecycleRuleDelete(**kw)
|
| Map a lifecycle rule deleting matching items.
|
| :type kw: dict
| :params kw: arguments passed to :class:`LifecycleRuleConditions`.
|
| Method resolution order:
| LifecycleRuleDelete
| builtins.dict
| builtins.object
|
| Methods defined here:
|
| __init__(self, **kw)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_api_repr(resource)
| Factory: construct instance from resource.
|
| :type resource: dict
| :param resource: mapping as returned from API call.
|
| :rtype: :class:`LifecycleRuleDelete`
| :returns: Instance created from resource.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class LifecycleRuleSetStorageClass(builtins.dict)
| LifecycleRuleSetStorageClass(storage_class, **kw)
|
| Map a lifecycle rule updating storage class of matching items.
|
| :type storage_class: str, one of :attr:`Bucket.STORAGE_CLASSES`.
| :param storage_class: new storage class to assign to matching items.
|
| :type kw: dict
| :params kw: arguments passed to :class:`LifecycleRuleConditions`.
|
| Method resolution order:
| LifecycleRuleSetStorageClass
| builtins.dict
| builtins.object
|
| Methods defined here:
|
| __init__(self, storage_class, **kw)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_api_repr(resource)
| Factory: construct instance from resource.
|
| :type resource: dict
| :param resource: mapping as returned from API call.
|
| :rtype: :class:`LifecycleRuleSetStorageClass`
| :returns: Instance created from resource.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class SoftDeletePolicy(builtins.dict)
| SoftDeletePolicy(bucket, **kw)
|
| Map a bucket's soft delete policy.
|
| See https://cloud.google.com/storage/docs/soft-delete
|
| :type bucket: :class:`Bucket`
| :param bucket: Bucket for which this instance is the policy.
|
| :type retention_duration_seconds: int
| :param retention_duration_seconds:
| (Optional) The period of time in seconds that soft-deleted objects in the bucket
| will be retained and cannot be permanently deleted.
|
| :type effective_time: :class:`datetime.datetime`
| :param effective_time:
| (Optional) When the bucket's soft delete policy is effective.
| This value should normally only be set by the back-end API.
|
| Method resolution order:
| SoftDeletePolicy
| builtins.dict
| builtins.object
|
| Methods defined here:
|
| __init__(self, bucket, **kw)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_api_repr(resource, bucket)
| Factory: construct instance from resource.
|
| :type resource: dict
| :param resource: mapping as returned from API call.
|
| :type bucket: :class:`Bucket`
| :params bucket: Bucket for which this instance is the policy.
|
| :rtype: :class:`SoftDeletePolicy`
| :returns: Instance created from resource.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| bucket
| Bucket for which this instance is the policy.
|
| :rtype: :class:`Bucket`
| :returns: the instance's bucket.
|
| effective_time
| Get the effective time of the bucket's soft delete policy.
|
| :rtype: datetime.datetime or ``NoneType``
| :returns: point-in time at which the bucket's soft delte policy is
| effective, or ``None`` if the property is not set.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| retention_duration_seconds
| Get the retention duration of the bucket's soft delete policy.
|
| :rtype: int or ``NoneType``
| :returns: The period of time in seconds that soft-deleted objects in the bucket
| will be retained and cannot be permanently deleted; Or ``None`` if the
| property is not set.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
DATA
ARCHIVE_STORAGE_CLASS = 'ARCHIVE'
COLDLINE_STORAGE_CLASS = 'COLDLINE'
DEFAULT_RETRY = <google.api_core.retry.retry_unary.Retry object>
DEFAULT_RETRY_IF_ETAG_IN_JSON = <google.cloud.storage.retry.Conditiona...
DEFAULT_RETRY_IF_GENERATION_SPECIFIED = <google.cloud.storage.retry.Co...
DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED = <google.cloud.storage.retr...
DUAL_REGION_LOCATION_TYPE = 'dual-region'
DURABLE_REDUCED_AVAILABILITY_LEGACY_STORAGE_CLASS = 'DURABLE_REDUCED_A...
ENFORCEMENT_MODE_FULLY_RESTRICTED = 'FullyRestricted'
ENFORCEMENT_MODE_NOT_RESTRICTED = 'NotRestricted'
MULTI_REGIONAL_LEGACY_STORAGE_CLASS = 'MULTI_REGIONAL'
MULTI_REGION_LOCATION_TYPE = 'multi-region'
NEARLINE_STORAGE_CLASS = 'NEARLINE'
NONE_PAYLOAD_FORMAT = 'NONE'
PUBLIC_ACCESS_PREVENTION_INHERITED = 'inherited'
REGIONAL_LEGACY_STORAGE_CLASS = 'REGIONAL'
REGION_LOCATION_TYPE = 'region'
STANDARD_STORAGE_CLASS = 'STANDARD'
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\google\cloud\storage\bucket.py
google-cloud-storage.client
Python Library Documentation: module google.cloud.storage.client in google.cloud.storage
NAME
google.cloud.storage.client - Client for interacting with the Google Cloud Storage API.
CLASSES
google.cloud.client.ClientWithProject(google.cloud.client.Client, google.cloud.client._ClientProjectMixin)
Client
class Client(google.cloud.client.ClientWithProject)
| Client(project=<object object at 0x0000022E2C0196D0>, credentials=None, _http=None, client_info=None, client_options=None, use_auth_w_custom_endpoint=True, extra_headers={}, *, api_key=None)
|
| Client to bundle configuration needed for API requests.
|
| :type project: str or None
| :param project: 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.
|
| :type credentials: :class:`~google.auth.credentials.Credentials`
| :param 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.
|
| :type _http: :class:`~requests.Session`
| :param _http: (Optional) HTTP object to make requests. Can be any object
| that defines ``request()`` with the same interface as
| :meth:`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.
|
| :type client_info: :class:`~google.api_core.client_info.ClientInfo`
| :param client_info:
| 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.
|
| :type client_options: :class:`~google.api_core.client_options.ClientOptions` or :class:`dict`
| :param client_options: (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.
|
| :type use_auth_w_custom_endpoint: bool
| :param use_auth_w_custom_endpoint:
| (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.
|
| :type extra_headers: dict
| :param extra_headers:
| (Optional) Custom headers to be sent with the requests attached to the client.
| For example, you can add custom audit logging headers.
|
| :type api_key: string
| :param api_key:
| (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.
|
| Method resolution order:
| Client
| google.cloud.client.ClientWithProject
| google.cloud.client.Client
| google.cloud.client._ClientFactoryMixin
| google.cloud.client._ClientProjectMixin
| builtins.object
|
| Methods defined here:
|
| __enter__(self)
|
| __exit__(self, exc_type, exc_val, exc_tb)
|
| __init__(self, project=<object object at 0x0000022E2C0196D0>, credentials=None, _http=None, client_info=None, client_options=None, use_auth_w_custom_endpoint=True, extra_headers={}, *, api_key=None)
| Initialize self. See help(type(self)) for accurate signature.
|
| batch(self, raise_exception=True)
| Factory constructor for batch object.
|
| .. note::
| This will not make an HTTP request; it simply instantiates
| a batch object owned by this client.
|
| :type raise_exception: bool
| :param raise_exception:
| (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.
|
| :rtype: :class:`google.cloud.storage.batch.Batch`
| :returns: The batch object created.
|
| bucket(self, bucket_name, user_project=None, generation=None)
| Factory constructor for bucket object.
|
| .. note::
| This will not make an HTTP request; it simply instantiates
| a bucket object owned by this client.
|
| :type bucket_name: str
| :param bucket_name: The name of the bucket to be instantiated.
|
| :type user_project: str
| :param user_project: (Optional) The project ID to be billed for API
| requests made via the bucket.
|
| :type generation: int
| :param generation: (Optional) If present, selects a specific revision of
| this bucket.
|
| :rtype: :class:`google.cloud.storage.bucket.Bucket`
| :returns: The bucket object created.
|
| close(self)
| Close the client and clear any cached metadata or active connections.
|
| create_bucket(self, bucket_or_name, requester_pays=None, project=None, user_project=None, location=None, data_locations=None, predefined_acl=None, predefined_default_object_acl=None, enable_object_retention=False, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Create a new bucket via a POST request.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/buckets/insert) and a [code sample](https://cloud.google.com/storage/docs/samples/storage-create-bucket#storage_create_bucket-python).
|
| Args:
| bucket_or_name (Union[ :class:`~google.cloud.storage.bucket.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 :meth:`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.
|
| Returns:
| google.cloud.storage.bucket.Bucket
| The newly created bucket.
|
| Raises:
| google.cloud.exceptions.Conflict
| If the bucket already exists.
|
| create_hmac_key(self, service_account_email, project_id=None, user_project=None, timeout=60, retry=None)
| Create an HMAC key for a service account.
|
| :type service_account_email: str
| :param service_account_email: e-mail address of the service account
|
| :type project_id: str
| :param project_id: (Optional) Explicit project ID for the key.
| Defaults to the client's project.
|
| :type user_project: str
| :param user_project: (Optional) This parameter is currently ignored.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry: (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.
|
| :rtype:
| Tuple[:class:`~google.cloud.storage.hmac_key.HMACKeyMetadata`, str]
| :returns: metadata for the created key, plus the bytes of the key's secret, which is an 40-character base64-encoded string.
|
| download_blob_to_file(self, blob_or_uri, file_obj, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='auto', retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, single_shot_download=False)
| Download the contents of a blob object or blob URI into a file-like object.
|
| See https://cloud.google.com/storage/docs/downloading-objects
|
| Args:
| blob_or_uri (Union[ :class:`~google.cloud.storage.blob.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: :ref:`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.
|
| generate_signed_post_policy_v4(self, bucket_name, blob_name, expiration, conditions=None, fields=None, credentials=None, virtual_hosted_style=False, bucket_bound_hostname=None, scheme='http', service_account_email=None, access_token=None)
| Generate a V4 signed policy object. Generated policy object allows user to upload objects with a POST request.
|
| .. note::
|
| Assumes ``credentials`` implements the
| :class:`google.auth.credentials.Signing` interface. Also assumes
| ``credentials`` has a ``service_account_email`` property which
| identifies the credentials.
|
| See a [code sample](https://github.com/googleapis/python-storage/blob/main/samples/snippets/storage_generate_signed_post_policy_v4.py).
|
| :type bucket_name: str
| :param bucket_name: Bucket name.
|
| :type blob_name: str
| :param blob_name: Object name.
|
| :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
| :param expiration: Policy expiration time. If a ``datetime`` instance is
| passed without an explicit ``tzinfo`` set, it will be
| assumed to be ``UTC``.
|
| :type conditions: list
| :param conditions: (Optional) List of POST policy conditions, which are
| used to restrict what is allowed in the request.
|
| :type fields: dict
| :param fields: (Optional) Additional elements to include into request.
|
| :type credentials: :class:`google.auth.credentials.Signing`
| :param credentials: (Optional) Credentials object with an associated private
| key to sign text.
|
| :type virtual_hosted_style: bool
| :param virtual_hosted_style:
| (Optional) If True, construct the URL relative to the bucket
| virtual hostname, e.g., '<bucket-name>.storage.googleapis.com'.
| Incompatible with bucket_bound_hostname.
|
| :type bucket_bound_hostname: str
| :param bucket_bound_hostname:
| (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
|
| :type scheme: str
| :param scheme:
| (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"``.
|
| :type service_account_email: str
| :param service_account_email: (Optional) E-mail address of the service account.
|
| :type access_token: str
| :param access_token: (Optional) Access token for a service account.
|
| :raises: :exc:`ValueError` when mutually exclusive arguments are used.
|
| :rtype: dict
| :returns: Signed POST policy.
|
| get_bucket(self, bucket_or_name, timeout=60, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, *, generation=None, soft_deleted=None)
| Retrieve a bucket via a GET request.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/buckets/get) and a [code sample](https://cloud.google.com/storage/docs/samples/storage-get-bucket-metadata#storage_get_bucket_metadata-python).
|
| Args:
| bucket_or_name (Union[ :class:`~google.cloud.storage.bucket.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 :meth:`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
|
| Returns:
| google.cloud.storage.bucket.Bucket
| The bucket matching the name provided.
|
| Raises:
| google.cloud.exceptions.NotFound
| If the bucket is not found.
|
| get_hmac_key_metadata(self, access_id, project_id=None, user_project=None, timeout=60)
| Return a metadata instance for the given HMAC key.
|
| :type access_id: str
| :param access_id: Unique ID of an existing key.
|
| :type project_id: str
| :param project_id: (Optional) Project ID of an existing key.
| Defaults to client's project.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type user_project: str
| :param user_project: (Optional) This parameter is currently ignored.
|
| get_service_account_email(self, project=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Get the email address of the project's GCS service account
|
| :type project: str
| :param project:
| (Optional) Project ID to use for retreiving GCS service account
| email address. Defaults to the client's project.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: str
| :returns: service account email address
|
| list_blobs(self, bucket_or_name, max_results=None, page_token=None, prefix=None, delimiter=None, start_offset=None, end_offset=None, include_trailing_delimiter=None, versions=None, projection='noAcl', fields=None, page_size=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, match_glob=None, include_folders_as_prefixes=None, soft_deleted=None, filter_=None)
| Return an iterator used to find blobs in the bucket.
|
| If :attr:`user_project` is set, bills the API request to that project.
|
| .. note::
| List prefixes (directories) in a bucket using a prefix and delimiter.
| See a [code sample](https://cloud.google.com/storage/docs/samples/storage-list-files-with-prefix#storage_list_files_with_prefix-python)
| listing objects using a prefix filter.
|
| Args:
| bucket_or_name (Union[ :class:`~google.cloud.storage.bucket.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 :meth:`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
|
| filter_ (str):
| (Optional) Filter string used to filter objects. See:
| https://docs.cloud.google.com/storage/docs/listing-objects#filter-by-object-contexts-syntax
|
| Returns:
| Iterator of all :class:`~google.cloud.storage.blob.Blob`
| in this bucket matching the arguments. The RPC call
| returns a response when the iterator is consumed.
|
| As part of the response, you'll also get back an iterator.prefixes entity that lists object names
| up to and including the requested delimiter. Duplicate entries are omitted from this list.
|
| list_buckets(self, max_results=None, page_token=None, prefix=None, projection='noAcl', fields=None, project=None, page_size=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, *, soft_deleted=None, return_partial_success=None)
| Get all buckets in the project associated to the client.
|
| This will not populate the list of blobs available in each
| bucket.
|
| See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/buckets/list) and a [code sample](https://cloud.google.com/storage/docs/samples/storage-list-buckets#storage_list_buckets-python).
|
| :type max_results: int
| :param max_results: (Optional) The maximum number of buckets to return.
|
| :type page_token: str
| :param page_token:
| (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.
|
| :type prefix: str
| :param prefix: (Optional) Filter results to buckets whose names begin
| with this prefix.
|
| :type projection: str
| :param projection:
| (Optional) Specifies the set of properties to return. If used, must
| be 'full' or 'noAcl'. Defaults to 'noAcl'.
|
| :type fields: str
| :param fields:
| (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'
|
| :type project: str
| :param project: (Optional) The project whose buckets are to be listed.
| If not passed, uses the project set on the client.
|
| :type page_size: int
| :param page_size: (Optional) Maximum number of buckets to return in each page.
| Defaults to a value set by the API.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :type soft_deleted: bool
| :param soft_deleted:
| (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 return_partial_success: bool
| :param return_partial_success:
| (Optional) If True, the response will also contain a list of
| unreachable buckets if the buckets are unavailable. The
| unreachable buckets will be available on the ``unreachable``
| attribute of the returned iterator.
|
| :rtype: :class:`~google.api_core.page_iterator.Iterator`
| :raises ValueError: if both ``project`` is ``None`` and the client's
| project is also ``None``.
| :returns: Iterator of all :class:`~google.cloud.storage.bucket.Bucket`
| belonging to this project.
|
| list_hmac_keys(self, max_results=None, service_account_email=None, show_deleted_keys=None, project_id=None, user_project=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| List HMAC keys for a project.
|
| :type max_results: int
| :param max_results:
| (Optional) Max number of keys to return in a given page.
|
| :type service_account_email: str
| :param service_account_email:
| (Optional) Limit keys to those created by the given service account.
|
| :type show_deleted_keys: bool
| :param show_deleted_keys:
| (Optional) Included deleted keys in the list. Default is to
| exclude them.
|
| :type project_id: str
| :param project_id: (Optional) Explicit project ID for the key.
| Defaults to the client's project.
|
| :type user_project: str
| :param user_project: (Optional) This parameter is currently ignored.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype:
| Tuple[:class:`~google.cloud.storage.hmac_key.HMACKeyMetadata`, str]
| :returns: metadata for the created key, plus the bytes of the key's secret, which is an 40-character base64-encoded string.
|
| lookup_bucket(self, bucket_name, timeout=60, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| 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 a NotFound exception.
|
| :type bucket_name: str
| :param bucket_name: The name of the bucket to get.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type if_metageneration_match: long
| :param if_metageneration_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration matches the given value.
|
| :type if_metageneration_not_match: long
| :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
| blob's current metageneration does not match the given value.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: :class:`google.cloud.storage.bucket.Bucket` or ``NoneType``
| :returns: The bucket matching the name provided or None if not found.
|
| restore_bucket(self, bucket_name, generation, projection='noAcl', if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Restores a soft-deleted bucket.
|
| :type bucket_name: str
| :param bucket_name: The name of the bucket to be restored.
|
| :type generation: int
| :param generation: Selects the specific revision of the bucket.
|
| :type projection: str
| :param projection:
| (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.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC.
|
| Users can configure non-default retry behavior. A ``None`` value will
| disable retries. See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
|
| :rtype: :class:`google.cloud.storage.bucket.Bucket`
| :returns: The restored Bucket.
|
| update_user_agent(self, user_agent)
| Update the user-agent string for this client.
|
| :type user_agent: str
| :param user_agent: The string to add to the user-agent.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| create_anonymous_client()
| Factory: return client with anonymous credentials.
|
| .. note::
|
| Such a client has only limited access to "public" buckets:
| listing their contents and downloading their blobs.
|
| :rtype: :class:`google.cloud.storage.client.Client`
| :returns: Instance w/ anonymous credentials and no project.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| api_endpoint
|
| current_batch
| Currently-active batch.
|
| :rtype: :class:`google.cloud.storage.batch.Batch` or ``NoneType`` (if
| no batch is active).
| :returns: The batch at the top of the batch stack.
|
| universe_domain
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| SCOPE = ('https://www.googleapis.com/auth/devstorage.full_control', 'h...
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from google.cloud.client.Client:
|
| __getstate__(self)
| Explicitly state that clients are not pickleable.
|
| ----------------------------------------------------------------------
| Class methods inherited from google.cloud.client._ClientFactoryMixin:
|
| from_service_account_info(info, *args, **kwargs)
| Factory to retrieve JSON credentials while creating client.
|
| :type info: dict
| :param info:
| The JSON object with a private key and other credentials
| information (downloaded from the Google APIs console).
|
| :type args: tuple
| :param args: Remaining positional arguments to pass to constructor.
|
| :param kwargs: Remaining keyword arguments to pass to constructor.
|
| :rtype: :class:`_ClientFactoryMixin`
| :returns: The client created with the retrieved JSON credentials.
| :raises TypeError: if there is a conflict with the kwargs
| and the credentials created by the factory.
|
| from_service_account_json(json_credentials_path, *args, **kwargs)
| Factory to retrieve JSON credentials while creating client.
|
| :type json_credentials_path: str
| :param json_credentials_path: The path to a private key file (this file
| was given to you when you created the
| service account). This file must contain
| a JSON object with a private key and
| other credentials information (downloaded
| from the Google APIs console).
|
| :type args: tuple
| :param args: Remaining positional arguments to pass to constructor.
|
| :param kwargs: Remaining keyword arguments to pass to constructor.
|
| :rtype: :class:`_ClientFactoryMixin`
| :returns: The client created with the retrieved JSON credentials.
| :raises TypeError: if there is a conflict with the kwargs
| and the credentials created by the factory.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from google.cloud.client._ClientFactoryMixin:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
DATA
DEFAULT_RETRY = <google.api_core.retry.retry_unary.Retry object>
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\google\cloud\storage\client.py
google-cloud-storage.constants
Python Library Documentation: module google.cloud.storage.constants in google.cloud.storage
NAME
google.cloud.storage.constants - Constants used across google.cloud.storage modules.
DESCRIPTION
See [Python Storage Client Constants Page](https://github.com/googleapis/python-storage/blob/main/google/cloud/storage/constants.py)
for constants used across storage classes, location types, public access prevention, etc.
DATA
ARCHIVE_STORAGE_CLASS = 'ARCHIVE'
COLDLINE_STORAGE_CLASS = 'COLDLINE'
DUAL_REGION_LOCATION_TYPE = 'dual-region'
DURABLE_REDUCED_AVAILABILITY_LEGACY_STORAGE_CLASS = 'DURABLE_REDUCED_A...
ENFORCEMENT_MODE_FULLY_RESTRICTED = 'FullyRestricted'
ENFORCEMENT_MODE_NOT_RESTRICTED = 'NotRestricted'
MULTI_REGIONAL_LEGACY_STORAGE_CLASS = 'MULTI_REGIONAL'
MULTI_REGION_LOCATION_TYPE = 'multi-region'
NEARLINE_STORAGE_CLASS = 'NEARLINE'
PUBLIC_ACCESS_PREVENTION_ENFORCED = 'enforced'
PUBLIC_ACCESS_PREVENTION_INHERITED = 'inherited'
PUBLIC_ACCESS_PREVENTION_UNSPECIFIED = 'unspecified'
REGIONAL_LEGACY_STORAGE_CLASS = 'REGIONAL'
REGION_LOCATION_TYPE = 'region'
RPO_ASYNC_TURBO = 'ASYNC_TURBO'
RPO_DEFAULT = 'DEFAULT'
STANDARD_STORAGE_CLASS = 'STANDARD'
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\google\cloud\storage\constants.py
google-cloud-storage.exceptions
Python Library Documentation: module google.cloud.storage.exceptions in google.cloud.storage
NAME
google.cloud.storage.exceptions - Exceptions raised by the library.
CLASSES
builtins.Exception(builtins.BaseException)
InvalidPathError
google.resumable_media.common.DataCorruption(builtins.Exception)
DataCorruption
google.resumable_media.common.InvalidResponse(builtins.Exception)
InvalidResponse
class DataCorruption(google.resumable_media.common.DataCorruption)
| DataCorruption(response, *args)
|
| Error class for corrupt media transfers.
|
| Args:
| response (object): The HTTP response which caused the failure.
| args (tuple): The positional arguments typically passed to an
| exception class.
|
| Method resolution order:
| DataCorruption
| google.resumable_media.common.DataCorruption
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, response, *args)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from google.resumable_media.common.DataCorruption:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class InvalidPathError(builtins.Exception)
| Raised when the provided path string is malformed.
|
| Method resolution order:
| InvalidPathError
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors defined here:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.Exception:
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class InvalidResponse(google.resumable_media.common.InvalidResponse)
| InvalidResponse(response, *args)
|
| Error class for responses which are not in the correct state.
|
| Args:
| response (object): The HTTP response which caused the failure.
| args (tuple): The positional arguments typically passed to an
| exception class.
|
| Method resolution order:
| InvalidResponse
| google.resumable_media.common.InvalidResponse
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, response, *args)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from google.resumable_media.common.InvalidResponse:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\google\cloud\storage\exceptions.py
google-cloud-storage.fileio
Python Library Documentation: module google.cloud.storage.fileio in google.cloud.storage
NAME
google.cloud.storage.fileio - Module for file-like access of blobs, usually invoked via Blob.open().
CLASSES
builtins.object
SlidingBuffer
io.BufferedIOBase(_io._BufferedIOBase, io.IOBase)
BlobReader
BlobWriter
class BlobReader(io.BufferedIOBase)
| BlobReader(blob, chunk_size=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, **download_kwargs)
|
| A file-like object that reads from a blob.
|
| :type blob: 'google.cloud.storage.blob.Blob'
| :param blob:
| The blob to download.
|
| :type chunk_size: long
| :param chunk_size:
| (Optional) The minimum number of bytes to read at a time. If fewer
| bytes than the chunk_size are requested, the remainder is buffered.
| The default is the chunk_size of the blob, or 40MiB.
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (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.
|
| Media operations (downloads and uploads) do not support non-default
| predicates in a Retry object. The default will always be used. Other
| configuration changes for Retry objects such as delays and deadlines
| are respected.
|
| :type download_kwargs: dict
| :param download_kwargs:
| Keyword arguments to pass to the underlying API calls.
| The following arguments are supported:
|
| - ``if_generation_match``
| - ``if_generation_not_match``
| - ``if_metageneration_match``
| - ``if_metageneration_not_match``
| - ``timeout``
| - ``raw_download``
| - ``single_shot_download``
|
| Note that download_kwargs (excluding ``raw_download`` and ``single_shot_download``) are also applied to blob.reload(),
| if a reload is needed during seek().
|
| Method resolution order:
| BlobReader
| io.BufferedIOBase
| _io._BufferedIOBase
| io.IOBase
| _io._IOBase
| builtins.object
|
| Methods defined here:
|
| __init__(self, blob, chunk_size=None, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, **download_kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| close(self)
| Flush and close the IO object.
|
| This method has no effect if the file is already closed.
|
| read(self, size=-1)
| Read and return up to n bytes.
|
| If the size argument is omitted, None, or negative, read and
| return all data until EOF.
|
| If the size argument is positive, and the underlying raw stream is
| not 'interactive', multiple raw reads may be issued to satisfy
| the byte count (unless EOF is reached first).
| However, for interactive raw streams (as well as sockets and pipes),
| at most one raw read will be issued, and a short result does not
| imply that EOF is imminent.
|
| Return an empty bytes object on EOF.
|
| Return None if the underlying raw stream was open in non-blocking
| mode and no data is available at the moment.
|
| read1(self, size=-1)
| Read and return up to size bytes, with at most one read() call to the underlying raw stream.
|
| Return an empty bytes object on EOF.
| A short result does not imply that EOF is imminent.
|
| readable(self)
| Return whether object was opened for reading.
|
| If False, read() will raise OSError.
|
| seek(self, pos, whence=0)
| Seek within the blob.
|
| This implementation of seek() uses knowledge of the blob size to
| validate that the reported position does not exceed the blob last byte.
| If the blob size is not already known it will call blob.reload().
|
| seekable(self)
| Return whether object supports random access.
|
| If False, seek(), tell() and truncate() will raise OSError.
| This method may need to do a test seek().
|
| writable(self)
| Return whether object was opened for writing.
|
| If False, write() will raise OSError.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| closed
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from _io._BufferedIOBase:
|
| detach(self, /)
| Disconnect this buffer from its underlying raw stream and return it.
|
| After the raw stream has been detached, the buffer is in an unusable
| state.
|
| readinto(self, buffer, /)
|
| readinto1(self, buffer, /)
|
| write(self, b, /)
| Write buffer b to the IO stream.
|
| Return the number of bytes written, which is always
| the length of b in bytes.
|
| Raise BlockingIOError if the buffer is full and the
| underlying raw stream cannot accept more data at the moment.
|
| ----------------------------------------------------------------------
| Methods inherited from _io._IOBase:
|
| __del__(...)
|
| __enter__(...)
|
| __exit__(...)
|
| __iter__(self, /)
| Implement iter(self).
|
| __next__(self, /)
| Implement next(self).
|
| fileno(self, /)
| Return underlying file descriptor if one exists.
|
| Raise OSError if the IO object does not use a file descriptor.
|
| flush(self, /)
| Flush write buffers, if applicable.
|
| This is not implemented for read-only and non-blocking streams.
|
| isatty(self, /)
| Return whether this is an 'interactive' stream.
|
| Return False if it can't be determined.
|
| readline(self, size=-1, /)
| Read and return a line from the stream.
|
| If size is specified, at most size bytes will be read.
|
| The line terminator is always b'\n' for binary files; for text
| files, the newlines argument to open can be used to select the line
| terminator(s) recognized.
|
| readlines(self, hint=-1, /)
| Return a list of lines from the stream.
|
| hint can be specified to control the number of lines read: no more
| lines will be read if the total size (in bytes/characters) of all
| lines so far exceeds hint.
|
| tell(self, /)
| Return current stream position.
|
| truncate(self, size=None, /)
| Truncate file to size bytes.
|
| File pointer is left unchanged. Size defaults to the current IO position
| as reported by tell(). Return the new size.
|
| writelines(self, lines, /)
| Write a list of lines to stream.
|
| Line separators are not added, so it is usual for each of the
| lines provided to have a line separator at the end.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from _io._IOBase:
|
| __dict__
class BlobWriter(io.BufferedIOBase)
| BlobWriter(blob, chunk_size=None, ignore_flush=False, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, **upload_kwargs)
|
| A file-like object that writes to a blob.
|
| :type blob: 'google.cloud.storage.blob.Blob'
| :param blob:
| The blob to which to write.
|
| :type chunk_size: long
| :param chunk_size:
| (Optional) The maximum number of bytes to buffer before sending data
| to the server, and the size of each request when data is sent.
| Writes are implemented as a "resumable upload", so chunk_size for
| writes must be exactly a multiple of 256KiB as with other resumable
| uploads. The default is the chunk_size of the blob, or 40 MiB.
|
| :type ignore_flush: bool
| :param ignore_flush:
| Makes flush() do nothing instead of raise an error. flush() without
| closing is not supported by the remote service and therefore calling it
| on this class normally results in io.UnsupportedOperation. However, that
| behavior is incompatible with some consumers and wrappers of file
| objects in Python, such as zipfile.ZipFile or io.TextIOWrapper. Setting
| ignore_flush will cause flush() to successfully do nothing, for
| compatibility with those contexts. The correct way to actually flush
| data to the remote server is to close() (using this object as a context
| manager is recommended).
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (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.
|
| Media operations (downloads and uploads) do not support non-default
| predicates in a Retry object. The default will always be used. Other
| configuration changes for Retry objects such as delays and deadlines
| are respected.
|
| :type upload_kwargs: dict
| :param upload_kwargs:
| Keyword arguments to pass to the underlying API
| calls. The following arguments are supported:
|
| - ``if_generation_match``
| - ``if_generation_not_match``
| - ``if_metageneration_match``
| - ``if_metageneration_not_match``
| - ``timeout``
| - ``content_type``
| - ``predefined_acl``
| - ``checksum``
|
| Method resolution order:
| BlobWriter
| io.BufferedIOBase
| _io._BufferedIOBase
| io.IOBase
| _io._IOBase
| builtins.object
|
| Methods defined here:
|
| __exit__(self, exc_type, exc_val, exc_tb)
|
| __init__(self, blob, chunk_size=None, ignore_flush=False, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>, **upload_kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| close(self)
| Flush and close the IO object.
|
| This method has no effect if the file is already closed.
|
| flush(self)
| Flush write buffers, if applicable.
|
| This is not implemented for read-only and non-blocking streams.
|
| readable(self)
| Return whether object was opened for reading.
|
| If False, read() will raise OSError.
|
| seekable(self)
| Return whether object supports random access.
|
| If False, seek(), tell() and truncate() will raise OSError.
| This method may need to do a test seek().
|
| tell(self)
| Return current stream position.
|
| terminate(self)
| Cancel the ResumableUpload.
|
| writable(self)
| Return whether object was opened for writing.
|
| If False, write() will raise OSError.
|
| write(self, b)
| Write buffer b to the IO stream.
|
| Return the number of bytes written, which is always
| the length of b in bytes.
|
| Raise BlockingIOError if the buffer is full and the
| underlying raw stream cannot accept more data at the moment.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| closed
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from _io._BufferedIOBase:
|
| detach(self, /)
| Disconnect this buffer from its underlying raw stream and return it.
|
| After the raw stream has been detached, the buffer is in an unusable
| state.
|
| read(self, size=-1, /)
| Read and return up to n bytes.
|
| If the size argument is omitted, None, or negative, read and
| return all data until EOF.
|
| If the size argument is positive, and the underlying raw stream is
| not 'interactive', multiple raw reads may be issued to satisfy
| the byte count (unless EOF is reached first).
| However, for interactive raw streams (as well as sockets and pipes),
| at most one raw read will be issued, and a short result does not
| imply that EOF is imminent.
|
| Return an empty bytes object on EOF.
|
| Return None if the underlying raw stream was open in non-blocking
| mode and no data is available at the moment.
|
| read1(self, size=-1, /)
| Read and return up to size bytes, with at most one read() call to the underlying raw stream.
|
| Return an empty bytes object on EOF.
| A short result does not imply that EOF is imminent.
|
| readinto(self, buffer, /)
|
| readinto1(self, buffer, /)
|
| ----------------------------------------------------------------------
| Methods inherited from _io._IOBase:
|
| __del__(...)
|
| __enter__(...)
|
| __iter__(self, /)
| Implement iter(self).
|
| __next__(self, /)
| Implement next(self).
|
| fileno(self, /)
| Return underlying file descriptor if one exists.
|
| Raise OSError if the IO object does not use a file descriptor.
|
| isatty(self, /)
| Return whether this is an 'interactive' stream.
|
| Return False if it can't be determined.
|
| readline(self, size=-1, /)
| Read and return a line from the stream.
|
| If size is specified, at most size bytes will be read.
|
| The line terminator is always b'\n' for binary files; for text
| files, the newlines argument to open can be used to select the line
| terminator(s) recognized.
|
| readlines(self, hint=-1, /)
| Return a list of lines from the stream.
|
| hint can be specified to control the number of lines read: no more
| lines will be read if the total size (in bytes/characters) of all
| lines so far exceeds hint.
|
| seek(self, offset, whence=0, /)
| Change the stream position to the given byte offset.
|
| offset
| The stream position, relative to 'whence'.
| whence
| The relative position to seek from.
|
| The offset is interpreted relative to the position indicated by whence.
| Values for whence are:
|
| * os.SEEK_SET or 0 -- start of stream (the default); offset should be zero or positive
| * os.SEEK_CUR or 1 -- current stream position; offset may be negative
| * os.SEEK_END or 2 -- end of stream; offset is usually negative
|
| Return the new absolute position.
|
| truncate(self, size=None, /)
| Truncate file to size bytes.
|
| File pointer is left unchanged. Size defaults to the current IO position
| as reported by tell(). Return the new size.
|
| writelines(self, lines, /)
| Write a list of lines to stream.
|
| Line separators are not added, so it is usual for each of the
| lines provided to have a line separator at the end.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from _io._IOBase:
|
| __dict__
class SlidingBuffer(builtins.object)
| A non-rewindable buffer that frees memory of chunks already consumed.
|
| This class is necessary because `google-resumable-media-python` expects
| `tell()` to work relative to the start of the file, not relative to a place
| in an intermediate buffer. Using this class, we present an external
| interface with consistent seek and tell behavior without having to actually
| store bytes already sent.
|
| Behavior of this class differs from an ordinary BytesIO buffer. `write()`
| will always append to the end of the file only and not change the seek
| position otherwise. `flush()` will delete all data already read (data to the
| left of the seek position). `tell()` will report the seek position of the
| buffer including all deleted data. Additionally the class implements
| __len__() which will report the size of the actual underlying buffer.
|
| This class does not attempt to implement the entire Python I/O interface.
|
| Methods defined here:
|
| __init__(self)
| Initialize self. See help(type(self)) for accurate signature.
|
| __len__(self)
| Determine the size of the buffer by seeking to the end.
|
| close(self)
|
| flush(self)
| Delete already-read data (all data to the left of the position).
|
| read(self, size=-1)
| Read and move the cursor.
|
| seek(self, pos)
| Seek to a position (backwards only) within the internal buffer.
|
| This implementation of seek() verifies that the seek destination is
| contained in _buffer. It will raise ValueError if the destination byte
| has already been purged from the buffer.
|
| The "whence" argument is not supported in this implementation.
|
| tell(self)
| Report how many bytes have been read from the buffer in total.
|
| write(self, b)
| Append to the end of the buffer without changing the position.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| closed
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
DATA
CHUNK_SIZE_MULTIPLE = 262144
DEFAULT_CHUNK_SIZE = 41943040
DEFAULT_RETRY = <google.api_core.retry.retry_unary.Retry object>
VALID_DOWNLOAD_KWARGS = {'if_generation_match', 'if_generation_not_mat...
VALID_UPLOAD_KWARGS = {'checksum', 'content_type', 'if_generation_matc...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\google\cloud\storage\fileio.py
google-cloud-storage.hmac_key
Python Library Documentation: module google.cloud.storage.hmac_key in google.cloud.storage
NAME
google.cloud.storage.hmac_key - Configure HMAC keys that can be used to authenticate requests to Google Cloud Storage.
DESCRIPTION
See [HMAC keys documentation](https://cloud.google.com/storage/docs/authentication/hmackeys)
CLASSES
builtins.object
HMACKeyMetadata
class HMACKeyMetadata(builtins.object)
| HMACKeyMetadata(client, access_id=None, project_id=None, user_project=None)
|
| Metadata about an HMAC service account key withn Cloud Storage.
|
| :type client: :class:`~google.cloud.stoage.client.Client`
| :param client: client associated with the key metadata.
|
| :type access_id: str
| :param access_id: (Optional) Unique ID of an existing key.
|
| :type project_id: str
| :param project_id: (Optional) Project ID of an existing key.
| Defaults to client's project.
|
| :type user_project: str
| :param user_project: (Optional) This parameter is currently ignored.
|
| Methods defined here:
|
| __eq__(self, other)
| Return self==value.
|
| __hash__(self)
| Return hash(self).
|
| __init__(self, client, access_id=None, project_id=None, user_project=None)
| Initialize self. See help(type(self)) for accurate signature.
|
| delete(self, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Delete the key from Cloud Storage.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :raises :class:`~google.api_core.exceptions.NotFound`:
| if the key does not exist on the back-end.
|
| exists(self, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Determine whether or not the key for this metadata exists.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: bool
| :returns: True if the key exists in Cloud Storage.
|
| reload(self, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Reload properties from Cloud Storage.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :raises :class:`~google.api_core.exceptions.NotFound`:
| if the key does not exist on the back-end.
|
| update(self, timeout=60, retry=<google.cloud.storage.retry.ConditionalRetryPolicy object at 0x0000022E2F920980>)
| Save writable properties to Cloud Storage.
|
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :raises :class:`~google.api_core.exceptions.NotFound`:
| if the key does not exist on the back-end.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| access_id
| Access ID of the key.
|
| :rtype: str or None
| :returns: unique identifier of the key within a project.
|
| etag
| ETag identifying the version of the key metadata.
|
| :rtype: str or None
| :returns: ETag for the version of the key's metadata.
|
| id
| ID of the key, including the Project ID and the Access ID.
|
| :rtype: str or None
| :returns: ID of the key.
|
| path
| Resource path for the metadata's key.
|
| project
| Project ID associated with the key.
|
| :rtype: str or None
| :returns: project identfier for the key.
|
| service_account_email
| Service account e-mail address associated with the key.
|
| :rtype: str or None
| :returns: e-mail address for the service account which created the key.
|
| time_created
| Retrieve the timestamp at which the HMAC key was created.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the bucket's resource has not been loaded
| from the server.
|
| updated
| Retrieve the timestamp at which the HMAC key was created.
|
| :rtype: :class:`datetime.datetime` or ``NoneType``
| :returns: Datetime object parsed from RFC3339 valid timestamp, or
| ``None`` if the bucket's resource has not been loaded
| from the server.
|
| user_project
| Project ID to be billed for API requests made via this bucket.
|
| This property is currently ignored by the server.
|
| :rtype: str
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| state
| Get / set key's state.
|
| One of:
| - ``ACTIVE``
| - ``INACTIVE``
| - ``DELETED``
|
| :rtype: str or None
| :returns: key's current state.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| ACTIVE_STATE = 'ACTIVE'
|
| DELETED_STATE = 'DELETED'
|
| INACTIVE_STATE = 'INACTIVE'
DATA
DEFAULT_RETRY = <google.api_core.retry.retry_unary.Retry object>
DEFAULT_RETRY_IF_ETAG_IN_JSON = <google.cloud.storage.retry.Conditiona...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\google\cloud\storage\hmac_key.py
google-cloud-storage.ip_filter
Python Library Documentation: module google.cloud.storage.ip_filter in google.cloud.storage
NAME
google.cloud.storage.ip_filter - IP Filter configuration for Google Cloud Storage Buckets.
CLASSES
builtins.object
IPFilter
PublicNetworkSource
VpcNetworkSource
class IPFilter(builtins.object)
| Represents a GCS Bucket IP Filter configuration.
|
| This class is a helper for constructing the IP Filter dictionary to be
| assigned to a bucket's ``ip_filter`` property.
|
| Methods defined here:
|
| __init__(self)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class PublicNetworkSource(builtins.object)
| PublicNetworkSource(allowed_ip_cidr_ranges: Optional[List[str]] = None)
|
| Represents a public network source for a GCS Bucket IP Filter.
|
| :type allowed_ip_cidr_ranges: list(str) or None
| :param allowed_ip_cidr_ranges: A list of public IPv4 or IPv6 ranges in
| CIDR notation that are allowed to access
| the bucket.
|
| Methods defined here:
|
| __init__(self, allowed_ip_cidr_ranges: Optional[List[str]] = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class VpcNetworkSource(builtins.object)
| VpcNetworkSource(network: str, allowed_ip_cidr_ranges: Optional[List[str]] = None)
|
| Represents a VPC network source for a GCS Bucket IP Filter.
|
| :type network: str
| :param network: The resource name of the VPC network.
|
| :type allowed_ip_cidr_ranges: list(str) or None
| :param allowed_ip_cidr_ranges: A list of IPv4 or IPv6 ranges in CIDR
| notation allowed to access the bucket
| from this VPC.
|
| Methods defined here:
|
| __init__(self, network: str, allowed_ip_cidr_ranges: Optional[List[str]] = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
DATA
Dict = typing.Dict
A generic version of dict.
List = typing.List
A generic version of list.
Optional = typing.Optional
Optional[X] is equivalent to Union[X, None].
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\google\cloud\storage\ip_filter.py
google-cloud-storage.notification
Python Library Documentation: module google.cloud.storage.notification in google.cloud.storage
NAME
google.cloud.storage.notification - Configure bucket notification resources to interact with Google Cloud Pub/Sub.
DESCRIPTION
See [Cloud Pub/Sub Notifications for Google Cloud Storage](https://cloud.google.com/storage/docs/pubsub-notifications)
CLASSES
builtins.object
BucketNotification
class BucketNotification(builtins.object)
| BucketNotification(bucket, topic_name=None, topic_project=None, custom_attributes=None, event_types=None, blob_name_prefix=None, payload_format='NONE', notification_id=None)
|
| Represent a single notification resource for a bucket.
|
| See: https://cloud.google.com/storage/docs/json_api/v1/notifications
|
| :type bucket: :class:`google.cloud.storage.bucket.Bucket`
| :param bucket: Bucket to which the notification is bound.
|
| :type topic_name: str
| :param topic_name:
| (Optional) Topic name to which notifications are published.
|
| :type topic_project: str
| :param topic_project:
| (Optional) Project ID of topic to which notifications are published.
| If not passed, uses the project ID of the bucket's client.
|
| :type custom_attributes: dict
| :param custom_attributes:
| (Optional) Additional attributes passed with notification events.
|
| :type event_types: list(str)
| :param event_types:
| (Optional) Event types for which notification events are published.
|
| :type blob_name_prefix: str
| :param blob_name_prefix:
| (Optional) Prefix of blob names for which notification events are
| published.
|
| :type payload_format: str
| :param payload_format:
| (Optional) Format of payload for notification events.
|
| :type notification_id: str
| :param notification_id:
| (Optional) The ID of the notification.
|
| Methods defined here:
|
| __init__(self, bucket, topic_name=None, topic_project=None, custom_attributes=None, event_types=None, blob_name_prefix=None, payload_format='NONE', notification_id=None)
| Initialize self. See help(type(self)) for accurate signature.
|
| create(self, client=None, timeout=60, retry=None)
| API wrapper: create the notification.
|
| See:
| https://cloud.google.com/storage/docs/json_api/v1/notifications/insert
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client`
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the notification's bucket.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :raises ValueError: if the notification already exists.
|
| delete(self, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Delete this notification.
|
| See:
| https://cloud.google.com/storage/docs/json_api/v1/notifications/delete
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :raises: :class:`google.api_core.exceptions.NotFound`:
| if the notification does not exist.
| :raises ValueError: if the notification has no ID.
|
| exists(self, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Test whether this notification exists.
|
| See:
| https://cloud.google.com/storage/docs/json_api/v1/notifications/get
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
| :rtype: bool
| :returns: True, if the notification exists, else False.
| :raises ValueError: if the notification has no ID.
|
| reload(self, client=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object at 0x0000022E2E9D89E0>)
| Update this notification from the server configuration.
|
| See:
| https://cloud.google.com/storage/docs/json_api/v1/notifications/get
|
| If :attr:`user_project` is set on the bucket, bills the API request
| to that project.
|
| :type client: :class:`~google.cloud.storage.client.Client` or
| ``NoneType``
| :param client: (Optional) The client to use. If not passed, falls back
| to the ``client`` stored on the current bucket.
| :type timeout: float or tuple
| :param timeout:
| (Optional) The amount of time, in seconds, to wait
| for the server response. See: :ref:`configuring_timeouts`
|
| :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
| :param retry:
| (Optional) How to retry the RPC. See: :ref:`configuring_retries`
|
|
| :raises ValueError: if the notification has no ID.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_api_repr(resource, bucket)
| Construct an instance from the JSON repr returned by the server.
|
| See: https://cloud.google.com/storage/docs/json_api/v1/notifications
|
| :type resource: dict
| :param resource: JSON repr of the notification
|
| :type bucket: :class:`google.cloud.storage.bucket.Bucket`
| :param bucket: Bucket to which the notification is bound.
|
| :rtype: :class:`BucketNotification`
| :returns: the new notification instance
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| blob_name_prefix
| Prefix of blob names for which notification events are published.
|
| bucket
| Bucket to which the notification is bound.
|
| client
| The client bound to this notfication.
|
| custom_attributes
| Custom attributes passed with notification events.
|
| etag
| Server-set ETag of notification resource.
|
| event_types
| Event types for which notification events are published.
|
| notification_id
| Server-set ID of notification resource.
|
| path
| The URL path for this notification.
|
| payload_format
| Format of payload of notification events.
|
| self_link
| Server-set ETag of notification resource.
|
| topic_name
| Topic name to which notifications are published.
|
| topic_project
| Project ID of topic to which notifications are published.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
DATA
DEFAULT_RETRY = <google.api_core.retry.retry_unary.Retry object>
JSON_API_V1_PAYLOAD_FORMAT = 'JSON_API_V1'
NONE_PAYLOAD_FORMAT = 'NONE'
OBJECT_ARCHIVE_EVENT_TYPE = 'OBJECT_ARCHIVE'
OBJECT_DELETE_EVENT_TYPE = 'OBJECT_DELETE'
OBJECT_FINALIZE_EVENT_TYPE = 'OBJECT_FINALIZE'
OBJECT_METADATA_UPDATE_EVENT_TYPE = 'OBJECT_METADATA_UPDATE'
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\google\cloud\storage\notification.py
google-cloud-storage.retry
Python Library Documentation: module google.cloud.storage.retry in google.cloud.storage
NAME
google.cloud.storage.retry - Helpers for configuring retries with exponential back-off.
DESCRIPTION
See [Retry Strategy for Google Cloud Storage](https://cloud.google.com/storage/docs/retry-strategy#client-libraries)
CLASSES
builtins.object
ConditionalRetryPolicy
class ConditionalRetryPolicy(builtins.object)
| ConditionalRetryPolicy(retry_policy, conditional_predicate, required_kwargs)
|
| A class for use when an API call is only conditionally safe to retry.
|
| This class is intended for use in inspecting the API call parameters of an
| API call to verify that any flags necessary to make the API call idempotent
| (such as specifying an ``if_generation_match`` or related flag) are present.
|
| It can be used in place of a ``retry.Retry`` object, in which case
| ``_http.Connection.api_request`` will pass the requested api call keyword
| arguments into the ``conditional_predicate`` and return the ``retry_policy``
| if the conditions are met.
|
| :type retry_policy: class:`google.api_core.retry.Retry`
| :param retry_policy: A retry object defining timeouts, persistence and which
| exceptions to retry.
|
| :type conditional_predicate: callable
| :param conditional_predicate: A callable that accepts exactly the number of
| arguments in ``required_kwargs``, in order, and returns True if the
| arguments have sufficient data to determine that the call is safe to
| retry (idempotent).
|
| :type required_kwargs: list(str)
| :param required_kwargs:
| A list of keyword argument keys that will be extracted from the API call
| and passed into the ``conditional predicate`` in order. For example,
| ``["query_params"]`` is commmonly used for preconditions in query_params.
|
| Methods defined here:
|
| __init__(self, retry_policy, conditional_predicate, required_kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| get_retry_policy_if_conditions_met(self, **kwargs)
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
FUNCTIONS
is_etag_in_data(data)
Return True if an etag is contained in the request body.
:type data: dict or None
:param data: A dict representing the request JSON body. If not passed, returns False.
is_etag_in_json(data)
``is_etag_in_json`` is supported for backwards-compatibility reasons only;
please use ``is_etag_in_data`` instead.
is_generation_specified(query_params)
Return True if generation or if_generation_match is specified.
is_metageneration_specified(query_params)
Return True if if_metageneration_match is specified.
DATA
DEFAULT_RETRY = <google.api_core.retry.retry_unary.Retry object>
DEFAULT_RETRY_IF_ETAG_IN_JSON = <google.cloud.storage.retry.Conditiona...
DEFAULT_RETRY_IF_GENERATION_SPECIFIED = <google.cloud.storage.retry.Co...
DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED = <google.cloud.storage.retr...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\google\cloud\storage\retry.py
google-cloud-storage.version
Python Library Documentation: module google.cloud.storage.version in google.cloud.storage
NAME
google.cloud.storage.version
DESCRIPTION
# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
VERSION
3.13.0
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\google\cloud\storage\version.py