diff --git a/google/cloud/_storage_v2/services/storage/async_client.py b/google/cloud/_storage_v2/services/storage/async_client.py index 55234cd28..4244fa791 100644 --- a/google/cloud/_storage_v2/services/storage/async_client.py +++ b/google/cloud/_storage_v2/services/storage/async_client.py @@ -80,22 +80,22 @@ class StorageAsyncClient: Resources are named as follows: - - Projects are referred to as they are defined by the Resource - Manager API, using strings like ``projects/123456`` or - ``projects/my-string-id``. - - - Buckets are named using string names of the form: - ``projects/{project}/buckets/{bucket}`` For globally unique - buckets, ``_`` may be substituted for the project. - - - Objects are uniquely identified by their name along with the name - of the bucket they belong to, as separate strings in this API. - For example: - - ReadObjectRequest { bucket: 'projects/_/buckets/my-bucket' - object: 'my-object' } Note that object names can contain ``/`` - characters, which are treated as any other character (no special - directory semantics). + - Projects are referred to as they are defined by the Resource + Manager API, using strings like ``projects/123456`` or + ``projects/my-string-id``. + + - Buckets are named using string names of the form: + ``projects/{project}/buckets/{bucket}`` For globally unique + buckets, ``_`` may be substituted for the project. + + - Objects are uniquely identified by their name along with the name + of the bucket they belong to, as separate strings in this API. For + example: + + ReadObjectRequest { bucket: 'projects/\_/buckets/my-bucket' + object: 'my-object' } Note that object names can contain ``/`` + characters, which are treated as any other character (no special + directory semantics). """ _client: StorageClient @@ -1006,19 +1006,19 @@ async def sample_get_iam_policy(): constraints based on attributes of the request, the resource, or both. To learn which resources support conditions in their IAM policies, see the [IAM - documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies). + documentation](https://cloud.google.com/iam/help/conditions/resource-policies). **JSON example:** - :literal:`\` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` + :literal:`` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` **YAML example:** - :literal:`\` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` + :literal:`` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` For a description of IAM and its features, see the [IAM - documentation](\ https://cloud.google.com/iam/docs/). + documentation](https://cloud.google.com/iam/docs/). """ # Create or coerce a protobuf request object. @@ -1161,19 +1161,19 @@ async def sample_set_iam_policy(): constraints based on attributes of the request, the resource, or both. To learn which resources support conditions in their IAM policies, see the [IAM - documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies). + documentation](https://cloud.google.com/iam/help/conditions/resource-policies). **JSON example:** - :literal:`\` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` + :literal:`` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` **YAML example:** - :literal:`\` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` + :literal:`` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` For a description of IAM and its features, see the [IAM - documentation](\ https://cloud.google.com/iam/docs/). + documentation](https://cloud.google.com/iam/docs/). """ # Create or coerce a protobuf request object. @@ -2578,41 +2578,41 @@ async def write_object( explicitly by the client or due to a network error or an error response from the server), the client should do as follows: - - Check the result Status of the stream, to determine if - writing can be resumed on this stream or must be restarted - from scratch (by calling ``StartResumableWrite()``). The - resumable errors are DEADLINE_EXCEEDED, INTERNAL, and - UNAVAILABLE. For each case, the client should use binary - exponential backoff before retrying. Additionally, writes can - be resumed after RESOURCE_EXHAUSTED errors, but only after - taking appropriate measures, which may include reducing - aggregate send rate across clients and/or requesting a quota - increase for your project. - - If the call to ``WriteObject`` returns ``ABORTED``, that - indicates concurrent attempts to update the resumable write, - caused either by multiple racing clients or by a single - client where the previous request was timed out on the client - side but nonetheless reached the server. In this case the - client should take steps to prevent further concurrent writes - (e.g., increase the timeouts, stop using more than one - process to perform the upload, etc.), and then should follow - the steps below for resuming the upload. - - For resumable errors, the client should call - ``QueryWriteStatus()`` and then continue writing from the - returned ``persisted_size``. This may be less than the amount - of data the client previously sent. Note also that it is - acceptable to send data starting at an offset earlier than - the returned ``persisted_size``; in this case, the service - will skip data at offsets that were already persisted - (without checking that it matches the previously written - data), and write only the data starting from the persisted - offset. Even though the data isn't written, it may still - incur a performance cost over resuming at the correct write - offset. This behavior can make client-side handling simpler - in some cases. - - Clients must only send data that is a multiple of 256 KiB per - message, unless the object is being finished with - ``finish_write`` set to ``true``. + - Check the result Status of the stream, to determine if writing + can be resumed on this stream or must be restarted from + scratch (by calling ``StartResumableWrite()``). The resumable + errors are DEADLINE_EXCEEDED, INTERNAL, and UNAVAILABLE. For + each case, the client should use binary exponential backoff + before retrying. Additionally, writes can be resumed after + RESOURCE_EXHAUSTED errors, but only after taking appropriate + measures, which may include reducing aggregate send rate + across clients and/or requesting a quota increase for your + project. + - If the call to ``WriteObject`` returns ``ABORTED``, that + indicates concurrent attempts to update the resumable write, + caused either by multiple racing clients or by a single client + where the previous request was timed out on the client side + but nonetheless reached the server. In this case the client + should take steps to prevent further concurrent writes (e.g., + increase the timeouts, stop using more than one process to + perform the upload, etc.), and then should follow the steps + below for resuming the upload. + - For resumable errors, the client should call + ``QueryWriteStatus()`` and then continue writing from the + returned ``persisted_size``. This may be less than the amount + of data the client previously sent. Note also that it is + acceptable to send data starting at an offset earlier than the + returned ``persisted_size``; in this case, the service will + skip data at offsets that were already persisted (without + checking that it matches the previously written data), and + write only the data starting from the persisted offset. Even + though the data isn't written, it may still incur a + performance cost over resuming at the correct write offset. + This behavior can make client-side handling simpler in some + cases. + - Clients must only send data that is a multiple of 256 KiB per + message, unless the object is being finished with + ``finish_write`` set to ``true``. The service will not view the object as complete until the client has sent a ``WriteObjectRequest`` with ``finish_write`` diff --git a/google/cloud/_storage_v2/services/storage/client.py b/google/cloud/_storage_v2/services/storage/client.py index ae1087cf6..82596dcd2 100644 --- a/google/cloud/_storage_v2/services/storage/client.py +++ b/google/cloud/_storage_v2/services/storage/client.py @@ -120,22 +120,22 @@ class StorageClient(metaclass=StorageClientMeta): Resources are named as follows: - - Projects are referred to as they are defined by the Resource - Manager API, using strings like ``projects/123456`` or - ``projects/my-string-id``. - - - Buckets are named using string names of the form: - ``projects/{project}/buckets/{bucket}`` For globally unique - buckets, ``_`` may be substituted for the project. - - - Objects are uniquely identified by their name along with the name - of the bucket they belong to, as separate strings in this API. - For example: - - ReadObjectRequest { bucket: 'projects/_/buckets/my-bucket' - object: 'my-object' } Note that object names can contain ``/`` - characters, which are treated as any other character (no special - directory semantics). + - Projects are referred to as they are defined by the Resource + Manager API, using strings like ``projects/123456`` or + ``projects/my-string-id``. + + - Buckets are named using string names of the form: + ``projects/{project}/buckets/{bucket}`` For globally unique + buckets, ``_`` may be substituted for the project. + + - Objects are uniquely identified by their name along with the name + of the bucket they belong to, as separate strings in this API. For + example: + + ReadObjectRequest { bucket: 'projects/\_/buckets/my-bucket' + object: 'my-object' } Note that object names can contain ``/`` + characters, which are treated as any other character (no special + directory semantics). """ @staticmethod @@ -1432,19 +1432,19 @@ def sample_get_iam_policy(): constraints based on attributes of the request, the resource, or both. To learn which resources support conditions in their IAM policies, see the [IAM - documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies). + documentation](https://cloud.google.com/iam/help/conditions/resource-policies). **JSON example:** - :literal:`\` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` + :literal:`` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` **YAML example:** - :literal:`\` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` + :literal:`` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` For a description of IAM and its features, see the [IAM - documentation](\ https://cloud.google.com/iam/docs/). + documentation](https://cloud.google.com/iam/docs/). """ # Create or coerce a protobuf request object. @@ -1588,19 +1588,19 @@ def sample_set_iam_policy(): constraints based on attributes of the request, the resource, or both. To learn which resources support conditions in their IAM policies, see the [IAM - documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies). + documentation](https://cloud.google.com/iam/help/conditions/resource-policies). **JSON example:** - :literal:`\` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` + :literal:`` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` **YAML example:** - :literal:`\` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` + :literal:`` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` For a description of IAM and its features, see the [IAM - documentation](\ https://cloud.google.com/iam/docs/). + documentation](https://cloud.google.com/iam/docs/). """ # Create or coerce a protobuf request object. @@ -2982,41 +2982,41 @@ def write_object( explicitly by the client or due to a network error or an error response from the server), the client should do as follows: - - Check the result Status of the stream, to determine if - writing can be resumed on this stream or must be restarted - from scratch (by calling ``StartResumableWrite()``). The - resumable errors are DEADLINE_EXCEEDED, INTERNAL, and - UNAVAILABLE. For each case, the client should use binary - exponential backoff before retrying. Additionally, writes can - be resumed after RESOURCE_EXHAUSTED errors, but only after - taking appropriate measures, which may include reducing - aggregate send rate across clients and/or requesting a quota - increase for your project. - - If the call to ``WriteObject`` returns ``ABORTED``, that - indicates concurrent attempts to update the resumable write, - caused either by multiple racing clients or by a single - client where the previous request was timed out on the client - side but nonetheless reached the server. In this case the - client should take steps to prevent further concurrent writes - (e.g., increase the timeouts, stop using more than one - process to perform the upload, etc.), and then should follow - the steps below for resuming the upload. - - For resumable errors, the client should call - ``QueryWriteStatus()`` and then continue writing from the - returned ``persisted_size``. This may be less than the amount - of data the client previously sent. Note also that it is - acceptable to send data starting at an offset earlier than - the returned ``persisted_size``; in this case, the service - will skip data at offsets that were already persisted - (without checking that it matches the previously written - data), and write only the data starting from the persisted - offset. Even though the data isn't written, it may still - incur a performance cost over resuming at the correct write - offset. This behavior can make client-side handling simpler - in some cases. - - Clients must only send data that is a multiple of 256 KiB per - message, unless the object is being finished with - ``finish_write`` set to ``true``. + - Check the result Status of the stream, to determine if writing + can be resumed on this stream or must be restarted from + scratch (by calling ``StartResumableWrite()``). The resumable + errors are DEADLINE_EXCEEDED, INTERNAL, and UNAVAILABLE. For + each case, the client should use binary exponential backoff + before retrying. Additionally, writes can be resumed after + RESOURCE_EXHAUSTED errors, but only after taking appropriate + measures, which may include reducing aggregate send rate + across clients and/or requesting a quota increase for your + project. + - If the call to ``WriteObject`` returns ``ABORTED``, that + indicates concurrent attempts to update the resumable write, + caused either by multiple racing clients or by a single client + where the previous request was timed out on the client side + but nonetheless reached the server. In this case the client + should take steps to prevent further concurrent writes (e.g., + increase the timeouts, stop using more than one process to + perform the upload, etc.), and then should follow the steps + below for resuming the upload. + - For resumable errors, the client should call + ``QueryWriteStatus()`` and then continue writing from the + returned ``persisted_size``. This may be less than the amount + of data the client previously sent. Note also that it is + acceptable to send data starting at an offset earlier than the + returned ``persisted_size``; in this case, the service will + skip data at offsets that were already persisted (without + checking that it matches the previously written data), and + write only the data starting from the persisted offset. Even + though the data isn't written, it may still incur a + performance cost over resuming at the correct write offset. + This behavior can make client-side handling simpler in some + cases. + - Clients must only send data that is a multiple of 256 KiB per + message, unless the object is being finished with + ``finish_write`` set to ``true``. The service will not view the object as complete until the client has sent a ``WriteObjectRequest`` with ``finish_write`` diff --git a/google/cloud/_storage_v2/services/storage/transports/grpc.py b/google/cloud/_storage_v2/services/storage/transports/grpc.py index 7ffe8465c..1738c3272 100644 --- a/google/cloud/_storage_v2/services/storage/transports/grpc.py +++ b/google/cloud/_storage_v2/services/storage/transports/grpc.py @@ -125,22 +125,22 @@ class StorageGrpcTransport(StorageTransport): Resources are named as follows: - - Projects are referred to as they are defined by the Resource - Manager API, using strings like ``projects/123456`` or - ``projects/my-string-id``. + - Projects are referred to as they are defined by the Resource + Manager API, using strings like ``projects/123456`` or + ``projects/my-string-id``. - - Buckets are named using string names of the form: - ``projects/{project}/buckets/{bucket}`` For globally unique - buckets, ``_`` may be substituted for the project. + - Buckets are named using string names of the form: + ``projects/{project}/buckets/{bucket}`` For globally unique + buckets, ``_`` may be substituted for the project. - - Objects are uniquely identified by their name along with the name - of the bucket they belong to, as separate strings in this API. - For example: + - Objects are uniquely identified by their name along with the name + of the bucket they belong to, as separate strings in this API. For + example: - ReadObjectRequest { bucket: 'projects/_/buckets/my-bucket' - object: 'my-object' } Note that object names can contain ``/`` - characters, which are treated as any other character (no special - directory semantics). + ReadObjectRequest { bucket: 'projects/\_/buckets/my-bucket' + object: 'my-object' } Note that object names can contain ``/`` + characters, which are treated as any other character (no special + directory semantics). This class defines the same methods as the primary client, so the primary client can load the underlying transport implementation @@ -887,41 +887,41 @@ def write_object( explicitly by the client or due to a network error or an error response from the server), the client should do as follows: - - Check the result Status of the stream, to determine if - writing can be resumed on this stream or must be restarted - from scratch (by calling ``StartResumableWrite()``). The - resumable errors are DEADLINE_EXCEEDED, INTERNAL, and - UNAVAILABLE. For each case, the client should use binary - exponential backoff before retrying. Additionally, writes can - be resumed after RESOURCE_EXHAUSTED errors, but only after - taking appropriate measures, which may include reducing - aggregate send rate across clients and/or requesting a quota - increase for your project. - - If the call to ``WriteObject`` returns ``ABORTED``, that - indicates concurrent attempts to update the resumable write, - caused either by multiple racing clients or by a single - client where the previous request was timed out on the client - side but nonetheless reached the server. In this case the - client should take steps to prevent further concurrent writes - (e.g., increase the timeouts, stop using more than one - process to perform the upload, etc.), and then should follow - the steps below for resuming the upload. - - For resumable errors, the client should call - ``QueryWriteStatus()`` and then continue writing from the - returned ``persisted_size``. This may be less than the amount - of data the client previously sent. Note also that it is - acceptable to send data starting at an offset earlier than - the returned ``persisted_size``; in this case, the service - will skip data at offsets that were already persisted - (without checking that it matches the previously written - data), and write only the data starting from the persisted - offset. Even though the data isn't written, it may still - incur a performance cost over resuming at the correct write - offset. This behavior can make client-side handling simpler - in some cases. - - Clients must only send data that is a multiple of 256 KiB per - message, unless the object is being finished with - ``finish_write`` set to ``true``. + - Check the result Status of the stream, to determine if writing + can be resumed on this stream or must be restarted from + scratch (by calling ``StartResumableWrite()``). The resumable + errors are DEADLINE_EXCEEDED, INTERNAL, and UNAVAILABLE. For + each case, the client should use binary exponential backoff + before retrying. Additionally, writes can be resumed after + RESOURCE_EXHAUSTED errors, but only after taking appropriate + measures, which may include reducing aggregate send rate + across clients and/or requesting a quota increase for your + project. + - If the call to ``WriteObject`` returns ``ABORTED``, that + indicates concurrent attempts to update the resumable write, + caused either by multiple racing clients or by a single client + where the previous request was timed out on the client side + but nonetheless reached the server. In this case the client + should take steps to prevent further concurrent writes (e.g., + increase the timeouts, stop using more than one process to + perform the upload, etc.), and then should follow the steps + below for resuming the upload. + - For resumable errors, the client should call + ``QueryWriteStatus()`` and then continue writing from the + returned ``persisted_size``. This may be less than the amount + of data the client previously sent. Note also that it is + acceptable to send data starting at an offset earlier than the + returned ``persisted_size``; in this case, the service will + skip data at offsets that were already persisted (without + checking that it matches the previously written data), and + write only the data starting from the persisted offset. Even + though the data isn't written, it may still incur a + performance cost over resuming at the correct write offset. + This behavior can make client-side handling simpler in some + cases. + - Clients must only send data that is a multiple of 256 KiB per + message, unless the object is being finished with + ``finish_write`` set to ``true``. The service will not view the object as complete until the client has sent a ``WriteObjectRequest`` with ``finish_write`` diff --git a/google/cloud/_storage_v2/services/storage/transports/grpc_asyncio.py b/google/cloud/_storage_v2/services/storage/transports/grpc_asyncio.py index fa2fa0e9d..c0cbc60cd 100644 --- a/google/cloud/_storage_v2/services/storage/transports/grpc_asyncio.py +++ b/google/cloud/_storage_v2/services/storage/transports/grpc_asyncio.py @@ -131,22 +131,22 @@ class StorageGrpcAsyncIOTransport(StorageTransport): Resources are named as follows: - - Projects are referred to as they are defined by the Resource - Manager API, using strings like ``projects/123456`` or - ``projects/my-string-id``. + - Projects are referred to as they are defined by the Resource + Manager API, using strings like ``projects/123456`` or + ``projects/my-string-id``. - - Buckets are named using string names of the form: - ``projects/{project}/buckets/{bucket}`` For globally unique - buckets, ``_`` may be substituted for the project. + - Buckets are named using string names of the form: + ``projects/{project}/buckets/{bucket}`` For globally unique + buckets, ``_`` may be substituted for the project. - - Objects are uniquely identified by their name along with the name - of the bucket they belong to, as separate strings in this API. - For example: + - Objects are uniquely identified by their name along with the name + of the bucket they belong to, as separate strings in this API. For + example: - ReadObjectRequest { bucket: 'projects/_/buckets/my-bucket' - object: 'my-object' } Note that object names can contain ``/`` - characters, which are treated as any other character (no special - directory semantics). + ReadObjectRequest { bucket: 'projects/\_/buckets/my-bucket' + object: 'my-object' } Note that object names can contain ``/`` + characters, which are treated as any other character (no special + directory semantics). This class defines the same methods as the primary client, so the primary client can load the underlying transport implementation @@ -914,41 +914,41 @@ def write_object( explicitly by the client or due to a network error or an error response from the server), the client should do as follows: - - Check the result Status of the stream, to determine if - writing can be resumed on this stream or must be restarted - from scratch (by calling ``StartResumableWrite()``). The - resumable errors are DEADLINE_EXCEEDED, INTERNAL, and - UNAVAILABLE. For each case, the client should use binary - exponential backoff before retrying. Additionally, writes can - be resumed after RESOURCE_EXHAUSTED errors, but only after - taking appropriate measures, which may include reducing - aggregate send rate across clients and/or requesting a quota - increase for your project. - - If the call to ``WriteObject`` returns ``ABORTED``, that - indicates concurrent attempts to update the resumable write, - caused either by multiple racing clients or by a single - client where the previous request was timed out on the client - side but nonetheless reached the server. In this case the - client should take steps to prevent further concurrent writes - (e.g., increase the timeouts, stop using more than one - process to perform the upload, etc.), and then should follow - the steps below for resuming the upload. - - For resumable errors, the client should call - ``QueryWriteStatus()`` and then continue writing from the - returned ``persisted_size``. This may be less than the amount - of data the client previously sent. Note also that it is - acceptable to send data starting at an offset earlier than - the returned ``persisted_size``; in this case, the service - will skip data at offsets that were already persisted - (without checking that it matches the previously written - data), and write only the data starting from the persisted - offset. Even though the data isn't written, it may still - incur a performance cost over resuming at the correct write - offset. This behavior can make client-side handling simpler - in some cases. - - Clients must only send data that is a multiple of 256 KiB per - message, unless the object is being finished with - ``finish_write`` set to ``true``. + - Check the result Status of the stream, to determine if writing + can be resumed on this stream or must be restarted from + scratch (by calling ``StartResumableWrite()``). The resumable + errors are DEADLINE_EXCEEDED, INTERNAL, and UNAVAILABLE. For + each case, the client should use binary exponential backoff + before retrying. Additionally, writes can be resumed after + RESOURCE_EXHAUSTED errors, but only after taking appropriate + measures, which may include reducing aggregate send rate + across clients and/or requesting a quota increase for your + project. + - If the call to ``WriteObject`` returns ``ABORTED``, that + indicates concurrent attempts to update the resumable write, + caused either by multiple racing clients or by a single client + where the previous request was timed out on the client side + but nonetheless reached the server. In this case the client + should take steps to prevent further concurrent writes (e.g., + increase the timeouts, stop using more than one process to + perform the upload, etc.), and then should follow the steps + below for resuming the upload. + - For resumable errors, the client should call + ``QueryWriteStatus()`` and then continue writing from the + returned ``persisted_size``. This may be less than the amount + of data the client previously sent. Note also that it is + acceptable to send data starting at an offset earlier than the + returned ``persisted_size``; in this case, the service will + skip data at offsets that were already persisted (without + checking that it matches the previously written data), and + write only the data starting from the persisted offset. Even + though the data isn't written, it may still incur a + performance cost over resuming at the correct write offset. + This behavior can make client-side handling simpler in some + cases. + - Clients must only send data that is a multiple of 256 KiB per + message, unless the object is being finished with + ``finish_write`` set to ``true``. The service will not view the object as complete until the client has sent a ``WriteObjectRequest`` with ``finish_write`` diff --git a/google/cloud/_storage_v2/types/storage.py b/google/cloud/_storage_v2/types/storage.py index bee559a2f..6e4e01855 100644 --- a/google/cloud/_storage_v2/types/storage.py +++ b/google/cloud/_storage_v2/types/storage.py @@ -146,7 +146,7 @@ class GetBucketRequest(proto.Message): This field is a member of `oneof`_ ``_if_metageneration_not_match``. read_mask (google.protobuf.field_mask_pb2.FieldMask): - Mask specifying which fields to read. A "*" field may be + Mask specifying which fields to read. A "\*" field may be used to indicate all fields. If no mask is specified, will default to all fields. @@ -269,7 +269,7 @@ class ListBucketsRequest(proto.Message): mask is specified, will default to all fields except items.owner, items.acl, and items.default_object_acl. - - may be used to mean "all fields". + - may be used to mean "all fields". This field is a member of `oneof`_ ``_read_mask``. """ @@ -860,7 +860,7 @@ class ReadObjectRequest(proto.Message): specified, will default to all fields except metadata.owner and metadata.acl. - - may be used to mean "all fields". + - may be used to mean "all fields". This field is a member of `oneof`_ ``_read_mask``. """ @@ -975,7 +975,7 @@ class GetObjectRequest(proto.Message): specified, will default to all fields except metadata.acl and metadata.owner. - - may be used to mean "all fields". + - may be used to mean "all fields". This field is a member of `oneof`_ ``_read_mask``. restore_token (str): @@ -1142,10 +1142,10 @@ class BidiReadObjectSpec(proto.Message): specified, will default to all fields except metadata.owner and metadata.acl. - - may be used to mean "all fields". As per - https://google.aip.dev/161, this field is deprecated. As - an alternative, grpc metadata can be used: - https://cloud.google.com/apis/docs/system-parameters#definitions + - may be used to mean "all fields". As per + https://google.aip.dev/161, this field is deprecated. As + an alternative, grpc metadata can be used: + https://cloud.google.com/apis/docs/system-parameters#definitions This field is a member of `oneof`_ ``_read_mask``. read_handle (google.cloud._storage_v2.types.BidiReadHandle): @@ -2095,7 +2095,7 @@ class ListObjectsRequest(proto.Message): mask is specified, will default to all fields except items.acl and items.owner. - - may be used to mean "all fields". + - may be used to mean "all fields". This field is a member of `oneof`_ ``_read_mask``. lexicographic_start (str): @@ -3187,12 +3187,12 @@ class Cors(proto.Message): Optional. The list of Origins eligible to receive CORS response headers. See [https://tools.ietf.org/html/rfc6454][RFC 6454] for more on - origins. Note: "*" is permitted in the list of origins, and + origins. Note: "\*" is permitted in the list of origins, and means "any Origin". method (MutableSequence[str]): Optional. The list of HTTP methods on which to include CORS response headers, (``GET``, ``OPTIONS``, ``POST``, etc) - Note: "*" is permitted in the list of methods, and means + Note: "\*" is permitted in the list of methods, and means "any method". response_header (MutableSequence[str]): Optional. The list of HTTP headers other than the @@ -4152,23 +4152,23 @@ class BucketAccessControl(proto.Message): Optional. The entity holding the permission, in one of the following forms: - - ``user-{userid}`` - - ``user-{email}`` - - ``group-{groupid}`` - - ``group-{email}`` - - ``domain-{domain}`` - - ``project-{team}-{projectnumber}`` - - ``project-{team}-{projectid}`` - - ``allUsers`` - - ``allAuthenticatedUsers`` Examples: - - The user ``liz@example.com`` would be - ``user-liz@example.com``. - - The group ``example@googlegroups.com`` would be - ``group-example@googlegroups.com`` - - All members of the Google Apps for Business domain - ``example.com`` would be ``domain-example.com`` For - project entities, ``project-{team}-{projectnumber}`` - format will be returned on response. + - ``user-{userid}`` + - ``user-{email}`` + - ``group-{groupid}`` + - ``group-{email}`` + - ``domain-{domain}`` + - ``project-{team}-{projectnumber}`` + - ``project-{team}-{projectid}`` + - ``allUsers`` + - ``allAuthenticatedUsers`` Examples: + - The user ``liz@example.com`` would be + ``user-liz@example.com``. + - The group ``example@googlegroups.com`` would be + ``group-example@googlegroups.com`` + - All members of the Google Apps for Business domain + ``example.com`` would be ``domain-example.com`` For + project entities, ``project-{team}-{projectnumber}`` + format will be returned on response. entity_alt (str): Output only. The alternative entity format, if exists. For project entities, ``project-{team}-{projectid}`` format will @@ -4767,32 +4767,32 @@ class ObjectAccessControl(proto.Message): Optional. The access permission for the entity. One of the following values: - - ``READER`` - - ``WRITER`` - - ``OWNER`` + - ``READER`` + - ``WRITER`` + - ``OWNER`` id (str): Optional. The ID of the access-control entry. entity (str): Optional. The entity holding the permission, in one of the following forms: - - ``user-{userid}`` - - ``user-{email}`` - - ``group-{groupid}`` - - ``group-{email}`` - - ``domain-{domain}`` - - ``project-{team}-{projectnumber}`` - - ``project-{team}-{projectid}`` - - ``allUsers`` - - ``allAuthenticatedUsers`` Examples: - - The user ``liz@example.com`` would be - ``user-liz@example.com``. - - The group ``example@googlegroups.com`` would be - ``group-example@googlegroups.com``. - - All members of the Google Apps for Business domain - ``example.com`` would be ``domain-example.com``. For - project entities, ``project-{team}-{projectnumber}`` - format will be returned on response. + - ``user-{userid}`` + - ``user-{email}`` + - ``group-{groupid}`` + - ``group-{email}`` + - ``domain-{domain}`` + - ``project-{team}-{projectnumber}`` + - ``project-{team}-{projectid}`` + - ``allUsers`` + - ``allAuthenticatedUsers`` Examples: + - The user ``liz@example.com`` would be + ``user-liz@example.com``. + - The group ``example@googlegroups.com`` would be + ``group-example@googlegroups.com``. + - All members of the Google Apps for Business domain + ``example.com`` would be ``domain-example.com``. For + project entities, ``project-{team}-{projectnumber}`` + format will be returned on response. entity_alt (str): Output only. The alternative entity format, if exists. For project entities, ``project-{team}-{projectid}`` format will