From 62edbe12a0c5a74eacb8d87ca265a19e6d27f890 Mon Sep 17 00:00:00 2001 From: larkee Date: Tue, 24 Dec 2019 14:38:21 +1100 Subject: [PATCH] feat(spanner): add deprecation warnings; add field_mask to get_instance; add endpoint_uris to Instance proto; update timeouts; make mutations optional for commits (via synth) --- docs/_static/custom.css | 2 +- docs/_templates/layout.html | 1 + .../gapic/database_admin_client.py | 231 +++++++------- .../gapic/database_admin_client_config.py | 10 +- .../database_admin_grpc_transport.py | 26 +- .../proto/spanner_database_admin.proto | 86 +++-- .../proto/spanner_database_admin_pb2_grpc.py | 7 +- .../gapic/instance_admin_client.py | 41 ++- .../proto/spanner_instance_admin.proto | 15 + .../proto/spanner_instance_admin_pb2.py | 115 +++++-- google/cloud/spanner_v1/batch.py | 2 +- .../cloud/spanner_v1/gapic/spanner_client.py | 41 ++- .../spanner_v1/gapic/spanner_client_config.py | 8 +- google/cloud/spanner_v1/proto/spanner.proto | 300 ++++++++++-------- .../spanner_v1/proto/spanner_pb2_grpc.py | 66 ++-- google/cloud/spanner_v1/transaction.py | 2 +- synth.metadata | 12 +- .../gapic/v1/test_database_admin_client_v1.py | 106 +++---- .../gapic/v1/test_instance_admin_client_v1.py | 12 +- tests/unit/gapic/v1/test_spanner_client_v1.py | 10 +- tests/unit/test_database.py | 2 +- tests/unit/test_session.py | 14 +- 22 files changed, 636 insertions(+), 473 deletions(-) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 9a6f9f8ddc..0abaf229fc 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -1,4 +1,4 @@ div#python2-eol { border-color: red; border-width: medium; -} \ No newline at end of file +} \ No newline at end of file diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index de457b2c27..228529efe2 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -1,3 +1,4 @@ + {% extends "!layout.html" %} {%- block content %} {%- if theme_fixed_sidebar|lower == 'true' %} diff --git a/google/cloud/spanner_admin_database_v1/gapic/database_admin_client.py b/google/cloud/spanner_admin_database_v1/gapic/database_admin_client.py index 52eaacd7dc..adaa0e6bc7 100644 --- a/google/cloud/spanner_admin_database_v1/gapic/database_admin_client.py +++ b/google/cloud/spanner_admin_database_v1/gapic/database_admin_client.py @@ -88,7 +88,12 @@ def from_service_account_file(cls, filename, *args, **kwargs): @classmethod def database_path(cls, project, instance, database): - """Return a fully-qualified database string.""" + """DEPRECATED. Return a fully-qualified database string.""" + warnings.warn( + "Resource name helper functions are deprecated.", + PendingDeprecationWarning, + stacklevel=1, + ) return google.api_core.path_template.expand( "projects/{project}/instances/{instance}/databases/{database}", project=project, @@ -98,7 +103,12 @@ def database_path(cls, project, instance, database): @classmethod def instance_path(cls, project, instance): - """Return a fully-qualified instance string.""" + """DEPRECATED. Return a fully-qualified instance string.""" + warnings.warn( + "Resource name helper functions are deprecated.", + PendingDeprecationWarning, + stacklevel=1, + ) return google.api_core.path_template.expand( "projects/{project}/instances/{instance}", project=project, @@ -218,110 +228,6 @@ def __init__( self._inner_api_calls = {} # Service calls - def list_databases( - self, - parent, - page_size=None, - retry=google.api_core.gapic_v1.method.DEFAULT, - timeout=google.api_core.gapic_v1.method.DEFAULT, - metadata=None, - ): - """ - Lists Cloud Spanner databases. - - Example: - >>> from google.cloud import spanner_admin_database_v1 - >>> - >>> client = spanner_admin_database_v1.DatabaseAdminClient() - >>> - >>> parent = client.instance_path('[PROJECT]', '[INSTANCE]') - >>> - >>> # Iterate over all results - >>> for element in client.list_databases(parent): - ... # process element - ... pass - >>> - >>> - >>> # Alternatively: - >>> - >>> # Iterate over results one page at a time - >>> for page in client.list_databases(parent).pages: - ... for element in page: - ... # process element - ... pass - - Args: - parent (str): Required. The instance whose databases should be listed. Values are of - the form ``projects//instances/``. - page_size (int): The maximum number of resources contained in the - underlying API response. If page streaming is performed per- - resource, this parameter does not affect the return value. If page - streaming is performed per-page, this determines the maximum number - of resources in a page. - retry (Optional[google.api_core.retry.Retry]): A retry object used - to retry requests. If ``None`` is specified, requests will - be retried using a default configuration. - timeout (Optional[float]): The amount of time, in seconds, to wait - for the request to complete. Note that if ``retry`` is - specified, the timeout applies to each individual attempt. - metadata (Optional[Sequence[Tuple[str, str]]]): Additional metadata - that is provided to the method. - - Returns: - A :class:`~google.api_core.page_iterator.PageIterator` instance. - An iterable of :class:`~google.cloud.spanner_admin_database_v1.types.Database` instances. - You can also iterate over the pages of the response - using its `pages` property. - - Raises: - google.api_core.exceptions.GoogleAPICallError: If the request - failed for any reason. - google.api_core.exceptions.RetryError: If the request failed due - to a retryable error and retry attempts failed. - ValueError: If the parameters are invalid. - """ - # Wrap the transport method to add retry and timeout logic. - if "list_databases" not in self._inner_api_calls: - self._inner_api_calls[ - "list_databases" - ] = google.api_core.gapic_v1.method.wrap_method( - self.transport.list_databases, - default_retry=self._method_configs["ListDatabases"].retry, - default_timeout=self._method_configs["ListDatabases"].timeout, - client_info=self._client_info, - ) - - request = spanner_database_admin_pb2.ListDatabasesRequest( - parent=parent, page_size=page_size - ) - if metadata is None: - metadata = [] - metadata = list(metadata) - try: - routing_header = [("parent", parent)] - except AttributeError: - pass - else: - routing_metadata = google.api_core.gapic_v1.routing_header.to_grpc_metadata( - routing_header - ) - metadata.append(routing_metadata) - - iterator = google.api_core.page_iterator.GRPCIterator( - client=None, - method=functools.partial( - self._inner_api_calls["list_databases"], - retry=retry, - timeout=timeout, - metadata=metadata, - ), - request=request, - items_field="databases", - request_token_field="page_token", - response_token_field="next_page_token", - ) - return iterator - def create_database( self, parent, @@ -769,7 +675,8 @@ def set_iam_policy( >>> >>> client = spanner_admin_database_v1.DatabaseAdminClient() >>> - >>> resource = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]') + >>> # TODO: Initialize `resource`: + >>> resource = '' >>> >>> # TODO: Initialize `policy`: >>> policy = {} @@ -854,7 +761,8 @@ def get_iam_policy( >>> >>> client = spanner_admin_database_v1.DatabaseAdminClient() >>> - >>> resource = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]') + >>> # TODO: Initialize `resource`: + >>> resource = '' >>> >>> response = client.get_iam_policy(resource) @@ -938,7 +846,8 @@ def test_iam_permissions( >>> >>> client = spanner_admin_database_v1.DatabaseAdminClient() >>> - >>> resource = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]') + >>> # TODO: Initialize `resource`: + >>> resource = '' >>> >>> # TODO: Initialize `permissions`: >>> permissions = [] @@ -1001,3 +910,107 @@ def test_iam_permissions( return self._inner_api_calls["test_iam_permissions"]( request, retry=retry, timeout=timeout, metadata=metadata ) + + def list_databases( + self, + parent, + page_size=None, + retry=google.api_core.gapic_v1.method.DEFAULT, + timeout=google.api_core.gapic_v1.method.DEFAULT, + metadata=None, + ): + """ + Lists Cloud Spanner databases. + + Example: + >>> from google.cloud import spanner_admin_database_v1 + >>> + >>> client = spanner_admin_database_v1.DatabaseAdminClient() + >>> + >>> parent = client.instance_path('[PROJECT]', '[INSTANCE]') + >>> + >>> # Iterate over all results + >>> for element in client.list_databases(parent): + ... # process element + ... pass + >>> + >>> + >>> # Alternatively: + >>> + >>> # Iterate over results one page at a time + >>> for page in client.list_databases(parent).pages: + ... for element in page: + ... # process element + ... pass + + Args: + parent (str): Required. The instance whose databases should be listed. Values are of + the form ``projects//instances/``. + page_size (int): The maximum number of resources contained in the + underlying API response. If page streaming is performed per- + resource, this parameter does not affect the return value. If page + streaming is performed per-page, this determines the maximum number + of resources in a page. + retry (Optional[google.api_core.retry.Retry]): A retry object used + to retry requests. If ``None`` is specified, requests will + be retried using a default configuration. + timeout (Optional[float]): The amount of time, in seconds, to wait + for the request to complete. Note that if ``retry`` is + specified, the timeout applies to each individual attempt. + metadata (Optional[Sequence[Tuple[str, str]]]): Additional metadata + that is provided to the method. + + Returns: + A :class:`~google.api_core.page_iterator.PageIterator` instance. + An iterable of :class:`~google.cloud.spanner_admin_database_v1.types.Database` instances. + You can also iterate over the pages of the response + using its `pages` property. + + Raises: + google.api_core.exceptions.GoogleAPICallError: If the request + failed for any reason. + google.api_core.exceptions.RetryError: If the request failed due + to a retryable error and retry attempts failed. + ValueError: If the parameters are invalid. + """ + # Wrap the transport method to add retry and timeout logic. + if "list_databases" not in self._inner_api_calls: + self._inner_api_calls[ + "list_databases" + ] = google.api_core.gapic_v1.method.wrap_method( + self.transport.list_databases, + default_retry=self._method_configs["ListDatabases"].retry, + default_timeout=self._method_configs["ListDatabases"].timeout, + client_info=self._client_info, + ) + + request = spanner_database_admin_pb2.ListDatabasesRequest( + parent=parent, page_size=page_size + ) + if metadata is None: + metadata = [] + metadata = list(metadata) + try: + routing_header = [("parent", parent)] + except AttributeError: + pass + else: + routing_metadata = google.api_core.gapic_v1.routing_header.to_grpc_metadata( + routing_header + ) + metadata.append(routing_metadata) + + iterator = google.api_core.page_iterator.GRPCIterator( + client=None, + method=functools.partial( + self._inner_api_calls["list_databases"], + retry=retry, + timeout=timeout, + metadata=metadata, + ), + request=request, + items_field="databases", + request_token_field="page_token", + response_token_field="next_page_token", + ) + return iterator diff --git a/google/cloud/spanner_admin_database_v1/gapic/database_admin_client_config.py b/google/cloud/spanner_admin_database_v1/gapic/database_admin_client_config.py index 46d60f0191..90c9f796e2 100644 --- a/google/cloud/spanner_admin_database_v1/gapic/database_admin_client_config.py +++ b/google/cloud/spanner_admin_database_v1/gapic/database_admin_client_config.py @@ -17,11 +17,6 @@ } }, "methods": { - "ListDatabases": { - "timeout_millis": 30000, - "retry_codes_name": "idempotent", - "retry_params_name": "default", - }, "CreateDatabase": { "timeout_millis": 3600000, "retry_codes_name": "non_idempotent", @@ -62,6 +57,11 @@ "retry_codes_name": "non_idempotent", "retry_params_name": "default", }, + "ListDatabases": { + "timeout_millis": 60000, + "retry_codes_name": "idempotent", + "retry_params_name": "default", + }, }, } } diff --git a/google/cloud/spanner_admin_database_v1/gapic/transports/database_admin_grpc_transport.py b/google/cloud/spanner_admin_database_v1/gapic/transports/database_admin_grpc_transport.py index 7308d265ea..24eab024c6 100644 --- a/google/cloud/spanner_admin_database_v1/gapic/transports/database_admin_grpc_transport.py +++ b/google/cloud/spanner_admin_database_v1/gapic/transports/database_admin_grpc_transport.py @@ -120,19 +120,6 @@ def channel(self): """ return self._channel - @property - def list_databases(self): - """Return the gRPC stub for :meth:`DatabaseAdminClient.list_databases`. - - Lists Cloud Spanner databases. - - Returns: - Callable: A callable which accepts the appropriate - deserialized request object and returns a - deserialized response object. - """ - return self._stubs["database_admin_stub"].ListDatabases - @property def create_database(self): """Return the gRPC stub for :meth:`DatabaseAdminClient.create_database`. @@ -262,3 +249,16 @@ def test_iam_permissions(self): deserialized response object. """ return self._stubs["database_admin_stub"].TestIamPermissions + + @property + def list_databases(self): + """Return the gRPC stub for :meth:`DatabaseAdminClient.list_databases`. + + Lists Cloud Spanner databases. + + Returns: + Callable: A callable which accepts the appropriate + deserialized request object and returns a + deserialized response object. + """ + return self._stubs["database_admin_stub"].ListDatabases diff --git a/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin.proto b/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin.proto index 8bd8f2c665..ea5200b4cb 100644 --- a/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin.proto +++ b/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin.proto @@ -34,6 +34,14 @@ option java_outer_classname = "SpannerDatabaseAdminProto"; option java_package = "com.google.spanner.admin.database.v1"; option php_namespace = "Google\\Cloud\\Spanner\\Admin\\Database\\V1"; +// The Instance resource is defined in `google.spanner.admin.instance.v1`. +// Because this is a separate, independent API (technically), we redefine +// the resource name pattern here. +option (google.api.resource_definition) = { + type: "spanner.googleapis.com/Instance" + pattern: "projects/{project}/instances/{instance}" +}; + // Cloud Spanner Database Admin API // // The Cloud Spanner Database Admin API can be used to create, drop, and @@ -58,10 +66,11 @@ service DatabaseAdmin { // have a name of the format `/operations/` and // can be used to track preparation of the database. The // [metadata][google.longrunning.Operation.metadata] field type is - // [CreateDatabaseMetadata][google.spanner.admin.database.v1.CreateDatabaseMetadata]. The - // [response][google.longrunning.Operation.response] field type is + // [CreateDatabaseMetadata][google.spanner.admin.database.v1.CreateDatabaseMetadata]. + // The [response][google.longrunning.Operation.response] field type is // [Database][google.spanner.admin.database.v1.Database], if successful. - rpc CreateDatabase(CreateDatabaseRequest) returns (google.longrunning.Operation) { + rpc CreateDatabase(CreateDatabaseRequest) + returns (google.longrunning.Operation) { option (google.api.http) = { post: "/v1/{parent=projects/*/instances/*}/databases" body: "*" @@ -87,8 +96,10 @@ service DatabaseAdmin { // the format `/operations/` and can be used to // track execution of the schema change(s). The // [metadata][google.longrunning.Operation.metadata] field type is - // [UpdateDatabaseDdlMetadata][google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata]. The operation has no response. - rpc UpdateDatabaseDdl(UpdateDatabaseDdlRequest) returns (google.longrunning.Operation) { + // [UpdateDatabaseDdlMetadata][google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata]. + // The operation has no response. + rpc UpdateDatabaseDdl(UpdateDatabaseDdlRequest) + returns (google.longrunning.Operation) { option (google.api.http) = { patch: "/v1/{database=projects/*/instances/*/databases/*}/ddl" body: "*" @@ -123,7 +134,8 @@ service DatabaseAdmin { // // Authorization requires `spanner.databases.setIamPolicy` // permission on [resource][google.iam.v1.SetIamPolicyRequest.resource]. - rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) { + rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) + returns (google.iam.v1.Policy) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*/databases/*}:setIamPolicy" body: "*" @@ -141,7 +153,8 @@ service DatabaseAdmin { // // Authorization requires `spanner.databases.getIamPolicy` permission on // [resource][google.iam.v1.GetIamPolicyRequest.resource]. - rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) { + rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) + returns (google.iam.v1.Policy) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*/databases/*}:getIamPolicy" body: "*" @@ -159,7 +172,8 @@ service DatabaseAdmin { // result in a NOT_FOUND error if the user has // `spanner.databases.list` permission on the containing Cloud // Spanner instance. Otherwise returns an empty set of permissions. - rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) { + rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) + returns (google.iam.v1.TestIamPermissionsResponse) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*/databases/*}:testIamPermissions" body: "*" @@ -203,7 +217,8 @@ message Database { State state = 2; } -// The request for [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases]. +// The request for +// [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases]. message ListDatabasesRequest { // Required. The instance whose databases should be listed. // Values are of the form `projects//instances/`. @@ -219,23 +234,26 @@ message ListDatabasesRequest { int32 page_size = 3; // If non-empty, `page_token` should contain a - // [next_page_token][google.spanner.admin.database.v1.ListDatabasesResponse.next_page_token] from a - // previous [ListDatabasesResponse][google.spanner.admin.database.v1.ListDatabasesResponse]. + // [next_page_token][google.spanner.admin.database.v1.ListDatabasesResponse.next_page_token] + // from a previous + // [ListDatabasesResponse][google.spanner.admin.database.v1.ListDatabasesResponse]. string page_token = 4; } -// The response for [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases]. +// The response for +// [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases]. message ListDatabasesResponse { // Databases that matched the request. repeated Database databases = 1; // `next_page_token` can be sent in a subsequent - // [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases] call to fetch more - // of the matching databases. + // [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases] + // call to fetch more of the matching databases. string next_page_token = 2; } -// The request for [CreateDatabase][google.spanner.admin.database.v1.DatabaseAdmin.CreateDatabase]. +// The request for +// [CreateDatabase][google.spanner.admin.database.v1.DatabaseAdmin.CreateDatabase]. message CreateDatabaseRequest { // Required. The name of the instance that will serve the new database. // Values are of the form `projects//instances/`. @@ -269,7 +287,8 @@ message CreateDatabaseMetadata { }]; } -// The request for [GetDatabase][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabase]. +// The request for +// [GetDatabase][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabase]. message GetDatabaseRequest { // Required. The name of the requested database. Values are of the form // `projects//instances//databases/`. @@ -295,8 +314,8 @@ message GetDatabaseRequest { // Each batch of statements is assigned a name which can be used with // the [Operations][google.longrunning.Operations] API to monitor // progress. See the -// [operation_id][google.spanner.admin.database.v1.UpdateDatabaseDdlRequest.operation_id] field for more -// details. +// [operation_id][google.spanner.admin.database.v1.UpdateDatabaseDdlRequest.operation_id] +// field for more details. message UpdateDatabaseDdlRequest { // Required. The database to update. string database = 1 [ @@ -316,18 +335,20 @@ message UpdateDatabaseDdlRequest { // // Specifying an explicit operation ID simplifies determining // whether the statements were executed in the event that the - // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl] call is replayed, - // or the return value is otherwise lost: the [database][google.spanner.admin.database.v1.UpdateDatabaseDdlRequest.database] and - // `operation_id` fields can be combined to form the + // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl] + // call is replayed, or the return value is otherwise lost: the + // [database][google.spanner.admin.database.v1.UpdateDatabaseDdlRequest.database] + // and `operation_id` fields can be combined to form the // [name][google.longrunning.Operation.name] of the resulting - // [longrunning.Operation][google.longrunning.Operation]: `/operations/`. + // [longrunning.Operation][google.longrunning.Operation]: + // `/operations/`. // // `operation_id` should be unique within the database, and must be // a valid identifier: `[a-z][a-z0-9_]*`. Note that // automatically-generated operation IDs always begin with an // underscore. If the named operation already exists, - // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl] returns - // `ALREADY_EXISTS`. + // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl] + // returns `ALREADY_EXISTS`. string operation_id = 3; } @@ -349,7 +370,8 @@ message UpdateDatabaseDdlMetadata { repeated google.protobuf.Timestamp commit_timestamps = 3; } -// The request for [DropDatabase][google.spanner.admin.database.v1.DatabaseAdmin.DropDatabase]. +// The request for +// [DropDatabase][google.spanner.admin.database.v1.DatabaseAdmin.DropDatabase]. message DropDatabaseRequest { // Required. The database to be dropped. string database = 1 [ @@ -360,7 +382,8 @@ message DropDatabaseRequest { ]; } -// The request for [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl]. +// The request for +// [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl]. message GetDatabaseDdlRequest { // Required. The database whose schema we wish to get. string database = 1 [ @@ -371,17 +394,10 @@ message GetDatabaseDdlRequest { ]; } -// The response for [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl]. +// The response for +// [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl]. message GetDatabaseDdlResponse { // A list of formatted DDL statements defining the schema of the database // specified in the request. repeated string statements = 1; } - -// The Instance resource is defined in `google.spanner.admin.instance.v1`. -// Because this is a separate, independent API (technically), we redefine -// the resource name pattern here. -option (google.api.resource_definition) = { - type: "spanner.googleapis.com/Instance" - pattern: "projects/{project}/instances/{instance}" -}; diff --git a/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin_pb2_grpc.py b/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin_pb2_grpc.py index 2491691e6b..7ea7ddb6fa 100644 --- a/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin_pb2_grpc.py +++ b/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin_pb2_grpc.py @@ -94,8 +94,8 @@ def CreateDatabase(self, request, context): have a name of the format `/operations/` and can be used to track preparation of the database. The [metadata][google.longrunning.Operation.metadata] field type is - [CreateDatabaseMetadata][google.spanner.admin.database.v1.CreateDatabaseMetadata]. The - [response][google.longrunning.Operation.response] field type is + [CreateDatabaseMetadata][google.spanner.admin.database.v1.CreateDatabaseMetadata]. + The [response][google.longrunning.Operation.response] field type is [Database][google.spanner.admin.database.v1.Database], if successful. """ context.set_code(grpc.StatusCode.UNIMPLEMENTED) @@ -116,7 +116,8 @@ def UpdateDatabaseDdl(self, request, context): the format `/operations/` and can be used to track execution of the schema change(s). The [metadata][google.longrunning.Operation.metadata] field type is - [UpdateDatabaseDdlMetadata][google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata]. The operation has no response. + [UpdateDatabaseDdlMetadata][google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata]. + The operation has no response. """ context.set_code(grpc.StatusCode.UNIMPLEMENTED) context.set_details("Method not implemented!") diff --git a/google/cloud/spanner_admin_instance_v1/gapic/instance_admin_client.py b/google/cloud/spanner_admin_instance_v1/gapic/instance_admin_client.py index c2c18a5840..a5bbe38642 100644 --- a/google/cloud/spanner_admin_instance_v1/gapic/instance_admin_client.py +++ b/google/cloud/spanner_admin_instance_v1/gapic/instance_admin_client.py @@ -105,7 +105,12 @@ def from_service_account_file(cls, filename, *args, **kwargs): @classmethod def instance_path(cls, project, instance): - """Return a fully-qualified instance string.""" + """DEPRECATED. Return a fully-qualified instance string.""" + warnings.warn( + "Resource name helper functions are deprecated.", + PendingDeprecationWarning, + stacklevel=1, + ) return google.api_core.path_template.expand( "projects/{project}/instances/{instance}", project=project, @@ -114,7 +119,12 @@ def instance_path(cls, project, instance): @classmethod def instance_config_path(cls, project, instance_config): - """Return a fully-qualified instance_config string.""" + """DEPRECATED. Return a fully-qualified instance_config string.""" + warnings.warn( + "Resource name helper functions are deprecated.", + PendingDeprecationWarning, + stacklevel=1, + ) return google.api_core.path_template.expand( "projects/{project}/instanceConfigs/{instance_config}", project=project, @@ -123,7 +133,12 @@ def instance_config_path(cls, project, instance_config): @classmethod def project_path(cls, project): - """Return a fully-qualified project string.""" + """DEPRECATED. Return a fully-qualified project string.""" + warnings.warn( + "Resource name helper functions are deprecated.", + PendingDeprecationWarning, + stacklevel=1, + ) return google.api_core.path_template.expand( "projects/{project}", project=project ) @@ -542,6 +557,7 @@ def list_instances( def get_instance( self, name, + field_mask=None, retry=google.api_core.gapic_v1.method.DEFAULT, timeout=google.api_core.gapic_v1.method.DEFAULT, metadata=None, @@ -561,6 +577,12 @@ def get_instance( Args: name (str): Required. The name of the requested instance. Values are of the form ``projects//instances/``. + field_mask (Union[dict, ~google.cloud.spanner_admin_instance_v1.types.FieldMask]): If field\_mask is present, specifies the subset of [][google.spanner.admin.instance.v1.Instance] fields + that should be returned. If absent, all [][google.spanner.admin.instance.v1.Instance] fields are + returned. + + If a dict is provided, it must be of the same form as the protobuf + message :class:`~google.cloud.spanner_admin_instance_v1.types.FieldMask` retry (Optional[google.api_core.retry.Retry]): A retry object used to retry requests. If ``None`` is specified, requests will be retried using a default configuration. @@ -591,7 +613,9 @@ def get_instance( client_info=self._client_info, ) - request = spanner_instance_admin_pb2.GetInstanceRequest(name=name) + request = spanner_instance_admin_pb2.GetInstanceRequest( + name=name, field_mask=field_mask + ) if metadata is None: metadata = [] metadata = list(metadata) @@ -980,7 +1004,8 @@ def set_iam_policy( >>> >>> client = spanner_admin_instance_v1.InstanceAdminClient() >>> - >>> resource = client.instance_path('[PROJECT]', '[INSTANCE]') + >>> # TODO: Initialize `resource`: + >>> resource = '' >>> >>> # TODO: Initialize `policy`: >>> policy = {} @@ -1065,7 +1090,8 @@ def get_iam_policy( >>> >>> client = spanner_admin_instance_v1.InstanceAdminClient() >>> - >>> resource = client.instance_path('[PROJECT]', '[INSTANCE]') + >>> # TODO: Initialize `resource`: + >>> resource = '' >>> >>> response = client.get_iam_policy(resource) @@ -1149,7 +1175,8 @@ def test_iam_permissions( >>> >>> client = spanner_admin_instance_v1.InstanceAdminClient() >>> - >>> resource = client.instance_path('[PROJECT]', '[INSTANCE]') + >>> # TODO: Initialize `resource`: + >>> resource = '' >>> >>> # TODO: Initialize `permissions`: >>> permissions = [] diff --git a/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin.proto b/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin.proto index 12b090e5d2..a437874133 100644 --- a/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin.proto +++ b/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin.proto @@ -397,6 +397,16 @@ message Instance { // as the string: name + "_" + value would prove problematic if we were to // allow "_" in a future release. map labels = 7; + + // Output only. The endpoint URIs based on the instance config. + // For example, instances located in a specific cloud region (or multi region) + // such as nam3, would have a nam3 specific endpoint URI. + // This URI is to be used implictly by SDK clients, with fallback to default + // URI. These endpoints are intended to optimize the network routing between + // the client and the instance's serving resources. + // If multiple endpoints are present, client may establish connections using + // any of the given URIs. + repeated string endpoint_uris = 8; } // The request for [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. @@ -455,6 +465,11 @@ message GetInstanceRequest { type: "spanner.googleapis.com/Instance" } ]; + + // If field_mask is present, specifies the subset of [][Instance] fields that + // should be returned. + // If absent, all [][Instance] fields are returned. + google.protobuf.FieldMask field_mask = 2; } // The request for [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance]. diff --git a/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin_pb2.py b/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin_pb2.py index d1fe569a9f..a70d64b0a8 100644 --- a/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin_pb2.py +++ b/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin_pb2.py @@ -37,7 +37,7 @@ "\n$com.google.spanner.admin.instance.v1B\031SpannerInstanceAdminProtoP\001ZHgoogle.golang.org/genproto/googleapis/spanner/admin/instance/v1;instance\252\002&Google.Cloud.Spanner.Admin.Instance.V1\312\002&Google\\Cloud\\Spanner\\Admin\\Instance\\V1" ), serialized_pb=_b( - '\nIgoogle/cloud/spanner/admin/instance_v1/proto/spanner_instance_admin.proto\x12 google.spanner.admin.instance.v1\x1a\x1cgoogle/api/annotations.proto\x1a\x17google/api/client.proto\x1a\x1fgoogle/api/field_behavior.proto\x1a\x19google/api/resource.proto\x1a\x1egoogle/iam/v1/iam_policy.proto\x1a\x1agoogle/iam/v1/policy.proto\x1a#google/longrunning/operations.proto\x1a\x1bgoogle/protobuf/empty.proto\x1a google/protobuf/field_mask.proto\x1a\x1fgoogle/protobuf/timestamp.proto"\xda\x01\n\x0bReplicaInfo\x12\x10\n\x08location\x18\x01 \x01(\t\x12G\n\x04type\x18\x02 \x01(\x0e\x32\x39.google.spanner.admin.instance.v1.ReplicaInfo.ReplicaType\x12\x1f\n\x17\x64\x65\x66\x61ult_leader_location\x18\x03 \x01(\x08"O\n\x0bReplicaType\x12\x14\n\x10TYPE_UNSPECIFIED\x10\x00\x12\x0e\n\nREAD_WRITE\x10\x01\x12\r\n\tREAD_ONLY\x10\x02\x12\x0b\n\x07WITNESS\x10\x03"\xd7\x01\n\x0eInstanceConfig\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x14\n\x0c\x64isplay_name\x18\x02 \x01(\t\x12?\n\x08replicas\x18\x03 \x03(\x0b\x32-.google.spanner.admin.instance.v1.ReplicaInfo:`\xea\x41]\n%spanner.googleapis.com/InstanceConfig\x12\x34projects/{project}/instanceConfigs/{instance_config}"\xbe\x03\n\x08Instance\x12\x0c\n\x04name\x18\x01 \x01(\t\x12:\n\x06\x63onfig\x18\x02 \x01(\tB*\xfa\x41\'\n%spanner.googleapis.com/InstanceConfig\x12\x14\n\x0c\x64isplay_name\x18\x03 \x01(\t\x12\x12\n\nnode_count\x18\x05 \x01(\x05\x12?\n\x05state\x18\x06 \x01(\x0e\x32\x30.google.spanner.admin.instance.v1.Instance.State\x12\x46\n\x06labels\x18\x07 \x03(\x0b\x32\x36.google.spanner.admin.instance.v1.Instance.LabelsEntry\x1a-\n\x0bLabelsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01"7\n\x05State\x12\x15\n\x11STATE_UNSPECIFIED\x10\x00\x12\x0c\n\x08\x43REATING\x10\x01\x12\t\n\x05READY\x10\x02:M\xea\x41J\n\x1fspanner.googleapis.com/Instance\x12\'projects/{project}/instances/{instance}"\x88\x01\n\x1aListInstanceConfigsRequest\x12\x43\n\x06parent\x18\x01 \x01(\tB3\xe0\x41\x02\xfa\x41-\n+cloudresourcemanager.googleapis.com/Project\x12\x11\n\tpage_size\x18\x02 \x01(\x05\x12\x12\n\npage_token\x18\x03 \x01(\t"\x82\x01\n\x1bListInstanceConfigsResponse\x12J\n\x10instance_configs\x18\x01 \x03(\x0b\x32\x30.google.spanner.admin.instance.v1.InstanceConfig\x12\x17\n\x0fnext_page_token\x18\x02 \x01(\t"W\n\x18GetInstanceConfigRequest\x12;\n\x04name\x18\x01 \x01(\tB-\xe0\x41\x02\xfa\x41\'\n%spanner.googleapis.com/InstanceConfig"K\n\x12GetInstanceRequest\x12\x35\n\x04name\x18\x01 \x01(\tB\'\xe0\x41\x02\xfa\x41!\n\x1fspanner.googleapis.com/Instance"\xb9\x01\n\x15\x43reateInstanceRequest\x12\x43\n\x06parent\x18\x01 \x01(\tB3\xe0\x41\x02\xfa\x41-\n+cloudresourcemanager.googleapis.com/Project\x12\x18\n\x0binstance_id\x18\x02 \x01(\tB\x03\xe0\x41\x02\x12\x41\n\x08instance\x18\x03 \x01(\x0b\x32*.google.spanner.admin.instance.v1.InstanceB\x03\xe0\x41\x02"\x92\x01\n\x14ListInstancesRequest\x12\x43\n\x06parent\x18\x01 \x01(\tB3\xe0\x41\x02\xfa\x41-\n+cloudresourcemanager.googleapis.com/Project\x12\x11\n\tpage_size\x18\x02 \x01(\x05\x12\x12\n\npage_token\x18\x03 \x01(\t\x12\x0e\n\x06\x66ilter\x18\x04 \x01(\t"o\n\x15ListInstancesResponse\x12=\n\tinstances\x18\x01 \x03(\x0b\x32*.google.spanner.admin.instance.v1.Instance\x12\x17\n\x0fnext_page_token\x18\x02 \x01(\t"\x8f\x01\n\x15UpdateInstanceRequest\x12\x41\n\x08instance\x18\x01 \x01(\x0b\x32*.google.spanner.admin.instance.v1.InstanceB\x03\xe0\x41\x02\x12\x33\n\nfield_mask\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.FieldMaskB\x03\xe0\x41\x02"N\n\x15\x44\x65leteInstanceRequest\x12\x35\n\x04name\x18\x01 \x01(\tB\'\xe0\x41\x02\xfa\x41!\n\x1fspanner.googleapis.com/Instance"\xe5\x01\n\x16\x43reateInstanceMetadata\x12<\n\x08instance\x18\x01 \x01(\x0b\x32*.google.spanner.admin.instance.v1.Instance\x12.\n\nstart_time\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12/\n\x0b\x63\x61ncel_time\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12,\n\x08\x65nd_time\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.Timestamp"\xe5\x01\n\x16UpdateInstanceMetadata\x12<\n\x08instance\x18\x01 \x01(\x0b\x32*.google.spanner.admin.instance.v1.Instance\x12.\n\nstart_time\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12/\n\x0b\x63\x61ncel_time\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12,\n\x08\x65nd_time\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.Timestamp2\xbf\x10\n\rInstanceAdmin\x12\xcc\x01\n\x13ListInstanceConfigs\x12<.google.spanner.admin.instance.v1.ListInstanceConfigsRequest\x1a=.google.spanner.admin.instance.v1.ListInstanceConfigsResponse"8\x82\xd3\xe4\x93\x02)\x12\'/v1/{parent=projects/*}/instanceConfigs\xda\x41\x06parent\x12\xb9\x01\n\x11GetInstanceConfig\x12:.google.spanner.admin.instance.v1.GetInstanceConfigRequest\x1a\x30.google.spanner.admin.instance.v1.InstanceConfig"6\x82\xd3\xe4\x93\x02)\x12\'/v1/{name=projects/*/instanceConfigs/*}\xda\x41\x04name\x12\xb4\x01\n\rListInstances\x12\x36.google.spanner.admin.instance.v1.ListInstancesRequest\x1a\x37.google.spanner.admin.instance.v1.ListInstancesResponse"2\x82\xd3\xe4\x93\x02#\x12!/v1/{parent=projects/*}/instances\xda\x41\x06parent\x12\xa1\x01\n\x0bGetInstance\x12\x34.google.spanner.admin.instance.v1.GetInstanceRequest\x1a*.google.spanner.admin.instance.v1.Instance"0\x82\xd3\xe4\x93\x02#\x12!/v1/{name=projects/*/instances/*}\xda\x41\x04name\x12\x9c\x02\n\x0e\x43reateInstance\x12\x37.google.spanner.admin.instance.v1.CreateInstanceRequest\x1a\x1d.google.longrunning.Operation"\xb1\x01\x82\xd3\xe4\x93\x02&"!/v1/{parent=projects/*}/instances:\x01*\xda\x41\x1bparent,instance_id,instance\xca\x41\x64\n)google.spanner.admin.instance.v1.Instance\x12\x37google.spanner.admin.instance.v1.CreateInstanceMetadata\x12\x9d\x02\n\x0eUpdateInstance\x12\x37.google.spanner.admin.instance.v1.UpdateInstanceRequest\x1a\x1d.google.longrunning.Operation"\xb2\x01\x82\xd3\xe4\x93\x02/2*/v1/{instance.name=projects/*/instances/*}:\x01*\xda\x41\x13instance,field_mask\xca\x41\x64\n)google.spanner.admin.instance.v1.Instance\x12\x37google.spanner.admin.instance.v1.UpdateInstanceMetadata\x12\x93\x01\n\x0e\x44\x65leteInstance\x12\x37.google.spanner.admin.instance.v1.DeleteInstanceRequest\x1a\x16.google.protobuf.Empty"0\x82\xd3\xe4\x93\x02#*!/v1/{name=projects/*/instances/*}\xda\x41\x04name\x12\x9a\x01\n\x0cSetIamPolicy\x12".google.iam.v1.SetIamPolicyRequest\x1a\x15.google.iam.v1.Policy"O\x82\xd3\xe4\x93\x02\x37"2/v1/{resource=projects/*/instances/*}:setIamPolicy:\x01*\xda\x41\x0fresource,policy\x12\x93\x01\n\x0cGetIamPolicy\x12".google.iam.v1.GetIamPolicyRequest\x1a\x15.google.iam.v1.Policy"H\x82\xd3\xe4\x93\x02\x37"2/v1/{resource=projects/*/instances/*}:getIamPolicy:\x01*\xda\x41\x08resource\x12\xc5\x01\n\x12TestIamPermissions\x12(.google.iam.v1.TestIamPermissionsRequest\x1a).google.iam.v1.TestIamPermissionsResponse"Z\x82\xd3\xe4\x93\x02="8/v1/{resource=projects/*/instances/*}:testIamPermissions:\x01*\xda\x41\x14resource,permissions\x1ax\xca\x41\x16spanner.googleapis.com\xd2\x41\\https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spanner.adminB\xdf\x01\n$com.google.spanner.admin.instance.v1B\x19SpannerInstanceAdminProtoP\x01ZHgoogle.golang.org/genproto/googleapis/spanner/admin/instance/v1;instance\xaa\x02&Google.Cloud.Spanner.Admin.Instance.V1\xca\x02&Google\\Cloud\\Spanner\\Admin\\Instance\\V1b\x06proto3' + '\nIgoogle/cloud/spanner/admin/instance_v1/proto/spanner_instance_admin.proto\x12 google.spanner.admin.instance.v1\x1a\x1cgoogle/api/annotations.proto\x1a\x17google/api/client.proto\x1a\x1fgoogle/api/field_behavior.proto\x1a\x19google/api/resource.proto\x1a\x1egoogle/iam/v1/iam_policy.proto\x1a\x1agoogle/iam/v1/policy.proto\x1a#google/longrunning/operations.proto\x1a\x1bgoogle/protobuf/empty.proto\x1a google/protobuf/field_mask.proto\x1a\x1fgoogle/protobuf/timestamp.proto"\xda\x01\n\x0bReplicaInfo\x12\x10\n\x08location\x18\x01 \x01(\t\x12G\n\x04type\x18\x02 \x01(\x0e\x32\x39.google.spanner.admin.instance.v1.ReplicaInfo.ReplicaType\x12\x1f\n\x17\x64\x65\x66\x61ult_leader_location\x18\x03 \x01(\x08"O\n\x0bReplicaType\x12\x14\n\x10TYPE_UNSPECIFIED\x10\x00\x12\x0e\n\nREAD_WRITE\x10\x01\x12\r\n\tREAD_ONLY\x10\x02\x12\x0b\n\x07WITNESS\x10\x03"\xd7\x01\n\x0eInstanceConfig\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x14\n\x0c\x64isplay_name\x18\x02 \x01(\t\x12?\n\x08replicas\x18\x03 \x03(\x0b\x32-.google.spanner.admin.instance.v1.ReplicaInfo:`\xea\x41]\n%spanner.googleapis.com/InstanceConfig\x12\x34projects/{project}/instanceConfigs/{instance_config}"\xd5\x03\n\x08Instance\x12\x0c\n\x04name\x18\x01 \x01(\t\x12:\n\x06\x63onfig\x18\x02 \x01(\tB*\xfa\x41\'\n%spanner.googleapis.com/InstanceConfig\x12\x14\n\x0c\x64isplay_name\x18\x03 \x01(\t\x12\x12\n\nnode_count\x18\x05 \x01(\x05\x12?\n\x05state\x18\x06 \x01(\x0e\x32\x30.google.spanner.admin.instance.v1.Instance.State\x12\x46\n\x06labels\x18\x07 \x03(\x0b\x32\x36.google.spanner.admin.instance.v1.Instance.LabelsEntry\x12\x15\n\rendpoint_uris\x18\x08 \x03(\t\x1a-\n\x0bLabelsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01"7\n\x05State\x12\x15\n\x11STATE_UNSPECIFIED\x10\x00\x12\x0c\n\x08\x43REATING\x10\x01\x12\t\n\x05READY\x10\x02:M\xea\x41J\n\x1fspanner.googleapis.com/Instance\x12\'projects/{project}/instances/{instance}"\x88\x01\n\x1aListInstanceConfigsRequest\x12\x43\n\x06parent\x18\x01 \x01(\tB3\xe0\x41\x02\xfa\x41-\n+cloudresourcemanager.googleapis.com/Project\x12\x11\n\tpage_size\x18\x02 \x01(\x05\x12\x12\n\npage_token\x18\x03 \x01(\t"\x82\x01\n\x1bListInstanceConfigsResponse\x12J\n\x10instance_configs\x18\x01 \x03(\x0b\x32\x30.google.spanner.admin.instance.v1.InstanceConfig\x12\x17\n\x0fnext_page_token\x18\x02 \x01(\t"W\n\x18GetInstanceConfigRequest\x12;\n\x04name\x18\x01 \x01(\tB-\xe0\x41\x02\xfa\x41\'\n%spanner.googleapis.com/InstanceConfig"{\n\x12GetInstanceRequest\x12\x35\n\x04name\x18\x01 \x01(\tB\'\xe0\x41\x02\xfa\x41!\n\x1fspanner.googleapis.com/Instance\x12.\n\nfield_mask\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.FieldMask"\xb9\x01\n\x15\x43reateInstanceRequest\x12\x43\n\x06parent\x18\x01 \x01(\tB3\xe0\x41\x02\xfa\x41-\n+cloudresourcemanager.googleapis.com/Project\x12\x18\n\x0binstance_id\x18\x02 \x01(\tB\x03\xe0\x41\x02\x12\x41\n\x08instance\x18\x03 \x01(\x0b\x32*.google.spanner.admin.instance.v1.InstanceB\x03\xe0\x41\x02"\x92\x01\n\x14ListInstancesRequest\x12\x43\n\x06parent\x18\x01 \x01(\tB3\xe0\x41\x02\xfa\x41-\n+cloudresourcemanager.googleapis.com/Project\x12\x11\n\tpage_size\x18\x02 \x01(\x05\x12\x12\n\npage_token\x18\x03 \x01(\t\x12\x0e\n\x06\x66ilter\x18\x04 \x01(\t"o\n\x15ListInstancesResponse\x12=\n\tinstances\x18\x01 \x03(\x0b\x32*.google.spanner.admin.instance.v1.Instance\x12\x17\n\x0fnext_page_token\x18\x02 \x01(\t"\x8f\x01\n\x15UpdateInstanceRequest\x12\x41\n\x08instance\x18\x01 \x01(\x0b\x32*.google.spanner.admin.instance.v1.InstanceB\x03\xe0\x41\x02\x12\x33\n\nfield_mask\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.FieldMaskB\x03\xe0\x41\x02"N\n\x15\x44\x65leteInstanceRequest\x12\x35\n\x04name\x18\x01 \x01(\tB\'\xe0\x41\x02\xfa\x41!\n\x1fspanner.googleapis.com/Instance"\xe5\x01\n\x16\x43reateInstanceMetadata\x12<\n\x08instance\x18\x01 \x01(\x0b\x32*.google.spanner.admin.instance.v1.Instance\x12.\n\nstart_time\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12/\n\x0b\x63\x61ncel_time\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12,\n\x08\x65nd_time\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.Timestamp"\xe5\x01\n\x16UpdateInstanceMetadata\x12<\n\x08instance\x18\x01 \x01(\x0b\x32*.google.spanner.admin.instance.v1.Instance\x12.\n\nstart_time\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12/\n\x0b\x63\x61ncel_time\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12,\n\x08\x65nd_time\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.Timestamp2\xbf\x10\n\rInstanceAdmin\x12\xcc\x01\n\x13ListInstanceConfigs\x12<.google.spanner.admin.instance.v1.ListInstanceConfigsRequest\x1a=.google.spanner.admin.instance.v1.ListInstanceConfigsResponse"8\x82\xd3\xe4\x93\x02)\x12\'/v1/{parent=projects/*}/instanceConfigs\xda\x41\x06parent\x12\xb9\x01\n\x11GetInstanceConfig\x12:.google.spanner.admin.instance.v1.GetInstanceConfigRequest\x1a\x30.google.spanner.admin.instance.v1.InstanceConfig"6\x82\xd3\xe4\x93\x02)\x12\'/v1/{name=projects/*/instanceConfigs/*}\xda\x41\x04name\x12\xb4\x01\n\rListInstances\x12\x36.google.spanner.admin.instance.v1.ListInstancesRequest\x1a\x37.google.spanner.admin.instance.v1.ListInstancesResponse"2\x82\xd3\xe4\x93\x02#\x12!/v1/{parent=projects/*}/instances\xda\x41\x06parent\x12\xa1\x01\n\x0bGetInstance\x12\x34.google.spanner.admin.instance.v1.GetInstanceRequest\x1a*.google.spanner.admin.instance.v1.Instance"0\x82\xd3\xe4\x93\x02#\x12!/v1/{name=projects/*/instances/*}\xda\x41\x04name\x12\x9c\x02\n\x0e\x43reateInstance\x12\x37.google.spanner.admin.instance.v1.CreateInstanceRequest\x1a\x1d.google.longrunning.Operation"\xb1\x01\x82\xd3\xe4\x93\x02&"!/v1/{parent=projects/*}/instances:\x01*\xda\x41\x1bparent,instance_id,instance\xca\x41\x64\n)google.spanner.admin.instance.v1.Instance\x12\x37google.spanner.admin.instance.v1.CreateInstanceMetadata\x12\x9d\x02\n\x0eUpdateInstance\x12\x37.google.spanner.admin.instance.v1.UpdateInstanceRequest\x1a\x1d.google.longrunning.Operation"\xb2\x01\x82\xd3\xe4\x93\x02/2*/v1/{instance.name=projects/*/instances/*}:\x01*\xda\x41\x13instance,field_mask\xca\x41\x64\n)google.spanner.admin.instance.v1.Instance\x12\x37google.spanner.admin.instance.v1.UpdateInstanceMetadata\x12\x93\x01\n\x0e\x44\x65leteInstance\x12\x37.google.spanner.admin.instance.v1.DeleteInstanceRequest\x1a\x16.google.protobuf.Empty"0\x82\xd3\xe4\x93\x02#*!/v1/{name=projects/*/instances/*}\xda\x41\x04name\x12\x9a\x01\n\x0cSetIamPolicy\x12".google.iam.v1.SetIamPolicyRequest\x1a\x15.google.iam.v1.Policy"O\x82\xd3\xe4\x93\x02\x37"2/v1/{resource=projects/*/instances/*}:setIamPolicy:\x01*\xda\x41\x0fresource,policy\x12\x93\x01\n\x0cGetIamPolicy\x12".google.iam.v1.GetIamPolicyRequest\x1a\x15.google.iam.v1.Policy"H\x82\xd3\xe4\x93\x02\x37"2/v1/{resource=projects/*/instances/*}:getIamPolicy:\x01*\xda\x41\x08resource\x12\xc5\x01\n\x12TestIamPermissions\x12(.google.iam.v1.TestIamPermissionsRequest\x1a).google.iam.v1.TestIamPermissionsResponse"Z\x82\xd3\xe4\x93\x02="8/v1/{resource=projects/*/instances/*}:testIamPermissions:\x01*\xda\x41\x14resource,permissions\x1ax\xca\x41\x16spanner.googleapis.com\xd2\x41\\https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spanner.adminB\xdf\x01\n$com.google.spanner.admin.instance.v1B\x19SpannerInstanceAdminProtoP\x01ZHgoogle.golang.org/genproto/googleapis/spanner/admin/instance/v1;instance\xaa\x02&Google.Cloud.Spanner.Admin.Instance.V1\xca\x02&Google\\Cloud\\Spanner\\Admin\\Instance\\V1b\x06proto3' ), dependencies=[ google_dot_api_dot_annotations__pb2.DESCRIPTOR, @@ -106,8 +106,8 @@ ], containing_type=None, serialized_options=None, - serialized_start=1171, - serialized_end=1226, + serialized_start=1194, + serialized_end=1249, ) _sym_db.RegisterEnumDescriptor(_INSTANCE_STATE) @@ -316,8 +316,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=1124, - serialized_end=1169, + serialized_start=1147, + serialized_end=1192, ) _INSTANCE = _descriptor.Descriptor( @@ -435,6 +435,24 @@ serialized_options=None, file=DESCRIPTOR, ), + _descriptor.FieldDescriptor( + name="endpoint_uris", + full_name="google.spanner.admin.instance.v1.Instance.endpoint_uris", + index=6, + number=8, + type=9, + cpp_type=9, + label=3, + has_default_value=False, + default_value=[], + message_type=None, + enum_type=None, + containing_type=None, + is_extension=False, + extension_scope=None, + serialized_options=None, + file=DESCRIPTOR, + ), ], extensions=[], nested_types=[_INSTANCE_LABELSENTRY], @@ -447,7 +465,7 @@ extension_ranges=[], oneofs=[], serialized_start=859, - serialized_end=1305, + serialized_end=1328, ) @@ -523,8 +541,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=1308, - serialized_end=1444, + serialized_start=1331, + serialized_end=1467, ) @@ -580,8 +598,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=1447, - serialized_end=1577, + serialized_start=1470, + serialized_end=1600, ) @@ -621,8 +639,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=1579, - serialized_end=1666, + serialized_start=1602, + serialized_end=1689, ) @@ -652,7 +670,25 @@ "\340A\002\372A!\n\037spanner.googleapis.com/Instance" ), file=DESCRIPTOR, - ) + ), + _descriptor.FieldDescriptor( + name="field_mask", + full_name="google.spanner.admin.instance.v1.GetInstanceRequest.field_mask", + index=1, + number=2, + type=11, + cpp_type=10, + label=1, + has_default_value=False, + default_value=None, + message_type=None, + enum_type=None, + containing_type=None, + is_extension=False, + extension_scope=None, + serialized_options=None, + file=DESCRIPTOR, + ), ], extensions=[], nested_types=[], @@ -662,8 +698,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=1668, - serialized_end=1743, + serialized_start=1691, + serialized_end=1814, ) @@ -739,8 +775,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=1746, - serialized_end=1931, + serialized_start=1817, + serialized_end=2002, ) @@ -834,8 +870,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=1934, - serialized_end=2080, + serialized_start=2005, + serialized_end=2151, ) @@ -891,8 +927,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=2082, - serialized_end=2193, + serialized_start=2153, + serialized_end=2264, ) @@ -948,8 +984,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=2196, - serialized_end=2339, + serialized_start=2267, + serialized_end=2410, ) @@ -989,8 +1025,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=2341, - serialized_end=2419, + serialized_start=2412, + serialized_end=2490, ) @@ -1082,8 +1118,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=2422, - serialized_end=2651, + serialized_start=2493, + serialized_end=2722, ) @@ -1175,8 +1211,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=2654, - serialized_end=2883, + serialized_start=2725, + serialized_end=2954, ) _REPLICAINFO.fields_by_name["type"].enum_type = _REPLICAINFO_REPLICATYPE @@ -1189,6 +1225,9 @@ _LISTINSTANCECONFIGSRESPONSE.fields_by_name[ "instance_configs" ].message_type = _INSTANCECONFIG +_GETINSTANCEREQUEST.fields_by_name[ + "field_mask" +].message_type = google_dot_protobuf_dot_field__mask__pb2._FIELDMASK _CREATEINSTANCEREQUEST.fields_by_name["instance"].message_type = _INSTANCE _LISTINSTANCESRESPONSE.fields_by_name["instances"].message_type = _INSTANCE _UPDATEINSTANCEREQUEST.fields_by_name["instance"].message_type = _INSTANCE @@ -1357,6 +1396,16 @@ characters being disallowed. For example, representing labels as the string: name + "*" + value would prove problematic if we were to allow "*" in a future release. + endpoint_uris: + Output only. The endpoint URIs based on the instance config. + For example, instances located in a specific cloud region (or + multi region) such as nam3, would have a nam3 specific + endpoint URI. This URI is to be used implictly by SDK clients, + with fallback to default URI. These endpoints are intended to + optimize the network routing between the client and the + instance's serving resources. If multiple endpoints are + present, client may establish connections using any of the + given URIs. """, # @@protoc_insertion_point(class_scope:google.spanner.admin.instance.v1.Instance) ), @@ -1454,6 +1503,10 @@ name: Required. The name of the requested instance. Values are of the form ``projects//instances/``. + field_mask: + If field\_mask is present, specifies the subset of + [][Instance] fields that should be returned. If absent, all + [][Instance] fields are returned. """, # @@protoc_insertion_point(class_scope:google.spanner.admin.instance.v1.GetInstanceRequest) ), @@ -1685,8 +1738,8 @@ serialized_options=_b( "\312A\026spanner.googleapis.com\322A\\https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spanner.admin" ), - serialized_start=2886, - serialized_end=4997, + serialized_start=2957, + serialized_end=5068, methods=[ _descriptor.MethodDescriptor( name="ListInstanceConfigs", diff --git a/google/cloud/spanner_v1/batch.py b/google/cloud/spanner_v1/batch.py index 3446416c89..e62763d7fd 100644 --- a/google/cloud/spanner_v1/batch.py +++ b/google/cloud/spanner_v1/batch.py @@ -149,7 +149,7 @@ def commit(self): txn_options = TransactionOptions(read_write=TransactionOptions.ReadWrite()) response = api.commit( self._session.name, - self._mutations, + mutations=self._mutations, single_use_transaction=txn_options, metadata=metadata, ) diff --git a/google/cloud/spanner_v1/gapic/spanner_client.py b/google/cloud/spanner_v1/gapic/spanner_client.py index 91fe9b9fa1..deb2a720ac 100644 --- a/google/cloud/spanner_v1/gapic/spanner_client.py +++ b/google/cloud/spanner_v1/gapic/spanner_client.py @@ -85,7 +85,12 @@ def from_service_account_file(cls, filename, *args, **kwargs): @classmethod def database_path(cls, project, instance, database): - """Return a fully-qualified database string.""" + """DEPRECATED. Return a fully-qualified database string.""" + warnings.warn( + "Resource name helper functions are deprecated.", + PendingDeprecationWarning, + stacklevel=1, + ) return google.api_core.path_template.expand( "projects/{project}/instances/{instance}/databases/{database}", project=project, @@ -95,7 +100,12 @@ def database_path(cls, project, instance, database): @classmethod def session_path(cls, project, instance, database, session): - """Return a fully-qualified session string.""" + """DEPRECATED. Return a fully-qualified session string.""" + warnings.warn( + "Resource name helper functions are deprecated.", + PendingDeprecationWarning, + stacklevel=1, + ) return google.api_core.path_template.expand( "projects/{project}/instances/{instance}/databases/{database}/sessions/{session}", project=project, @@ -1028,9 +1038,9 @@ def execute_batch_dml( If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.Statement` - seqno (long): Required. A per-transaction sequence number used to identify this request. This field - makes each request idempotent such that if the request is received multiple - times, at most one will succeed. + seqno (long): Required. A per-transaction sequence number used to identify this request. + This field makes each request idempotent such that if the request is + received multiple times, at most one will succeed. The sequence number must be monotonically increasing within the transaction. If a request arrives for the first time with an out-of-order @@ -1449,9 +1459,9 @@ def begin_transaction( def commit( self, session, - mutations, transaction_id=None, single_use_transaction=None, + mutations=None, retry=google.api_core.gapic_v1.method.DEFAULT, timeout=google.api_core.gapic_v1.method.DEFAULT, metadata=None, @@ -1473,19 +1483,10 @@ def commit( >>> >>> session = client.session_path('[PROJECT]', '[INSTANCE]', '[DATABASE]', '[SESSION]') >>> - >>> # TODO: Initialize `mutations`: - >>> mutations = [] - >>> - >>> response = client.commit(session, mutations) + >>> response = client.commit(session) Args: session (str): Required. The session in which the transaction to be committed is running. - mutations (list[Union[dict, ~google.cloud.spanner_v1.types.Mutation]]): The mutations to be executed when this transaction commits. All - mutations are applied atomically, in the order they appear in - this list. - - If a dict is provided, it must be of the same form as the protobuf - message :class:`~google.cloud.spanner_v1.types.Mutation` transaction_id (bytes): Commit a previously-started transaction. single_use_transaction (Union[dict, ~google.cloud.spanner_v1.types.TransactionOptions]): Execute mutations in a temporary transaction. Note that unlike commit of a previously-started transaction, commit with a temporary transaction is @@ -1497,6 +1498,12 @@ def commit( If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.TransactionOptions` + mutations (list[Union[dict, ~google.cloud.spanner_v1.types.Mutation]]): The mutations to be executed when this transaction commits. All + mutations are applied atomically, in the order they appear in + this list. + + If a dict is provided, it must be of the same form as the protobuf + message :class:`~google.cloud.spanner_v1.types.Mutation` retry (Optional[google.api_core.retry.Retry]): A retry object used to retry requests. If ``None`` is specified, requests will be retried using a default configuration. @@ -1535,9 +1542,9 @@ def commit( request = spanner_pb2.CommitRequest( session=session, - mutations=mutations, transaction_id=transaction_id, single_use_transaction=single_use_transaction, + mutations=mutations, ) if metadata is None: metadata = [] diff --git a/google/cloud/spanner_v1/gapic/spanner_client_config.py b/google/cloud/spanner_v1/gapic/spanner_client_config.py index 333f72afe2..44b81c5fb9 100644 --- a/google/cloud/spanner_v1/gapic/spanner_client_config.py +++ b/google/cloud/spanner_v1/gapic/spanner_client_config.py @@ -11,18 +11,18 @@ "initial_retry_delay_millis": 250, "retry_delay_multiplier": 1.3, "max_retry_delay_millis": 32000, - "initial_rpc_timeout_millis": 360000, + "initial_rpc_timeout_millis": 3600000, "rpc_timeout_multiplier": 1.0, - "max_rpc_timeout_millis": 360000, + "max_rpc_timeout_millis": 3600000, "total_timeout_millis": 3600000, }, "streaming": { "initial_retry_delay_millis": 250, "retry_delay_multiplier": 1.3, "max_retry_delay_millis": 32000, - "initial_rpc_timeout_millis": 360000, + "initial_rpc_timeout_millis": 3600000, "rpc_timeout_multiplier": 1.0, - "max_rpc_timeout_millis": 360000, + "max_rpc_timeout_millis": 3600000, "total_timeout_millis": 3600000, }, "long_running": { diff --git a/google/cloud/spanner_v1/proto/spanner.proto b/google/cloud/spanner_v1/proto/spanner.proto index 9cdbd7881c..2ff4c8db89 100644 --- a/google/cloud/spanner_v1/proto/spanner.proto +++ b/google/cloud/spanner_v1/proto/spanner.proto @@ -38,6 +38,14 @@ option java_outer_classname = "SpannerProto"; option java_package = "com.google.spanner.v1"; option php_namespace = "Google\\Cloud\\Spanner\\V1"; +// The Database resource is defined in `google.spanner.admin.database.v1`. +// Because this is a separate, independent API (technically), we redefine +// the resource name pattern here. +option (google.api.resource_definition) = { + type: "spanner.googleapis.com/Database" + pattern: "projects/{project}/instances/{instance}/databases/{database}" +}; + // Cloud Spanner API // // The Cloud Spanner API can be used to manage sessions and execute @@ -79,7 +87,8 @@ service Spanner { // // This API can be used to initialize a session cache on the clients. // See https://goo.gl/TgSFN2 for best practices on session cache management. - rpc BatchCreateSessions(BatchCreateSessionsRequest) returns (BatchCreateSessionsResponse) { + rpc BatchCreateSessions(BatchCreateSessionsRequest) + returns (BatchCreateSessionsResponse) { option (google.api.http) = { post: "/v1/{database=projects/*/instances/*/databases/*}/sessions:batchCreate" body: "*" @@ -122,10 +131,12 @@ service Spanner { // // Operations inside read-write transactions might return `ABORTED`. If // this occurs, the application should restart the transaction from - // the beginning. See [Transaction][google.spanner.v1.Transaction] for more details. + // the beginning. See [Transaction][google.spanner.v1.Transaction] for more + // details. // // Larger result sets can be fetched in streaming fashion by calling - // [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] instead. + // [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] + // instead. rpc ExecuteSql(ExecuteSqlRequest) returns (ResultSet) { option (google.api.http) = { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeSql" @@ -133,11 +144,11 @@ service Spanner { }; } - // Like [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], except returns the result - // set as a stream. Unlike [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], there - // is no limit on the size of the returned result set. However, no - // individual row in the result set can exceed 100 MiB, and no - // column value can exceed 10 MiB. + // Like [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], except returns the + // result set as a stream. Unlike + // [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], there is no limit on + // the size of the returned result set. However, no individual row in the + // result set can exceed 100 MiB, and no column value can exceed 10 MiB. rpc ExecuteStreamingSql(ExecuteSqlRequest) returns (stream PartialResultSet) { option (google.api.http) = { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeStreamingSql" @@ -150,13 +161,15 @@ service Spanner { // [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. // // Statements are executed in sequential order. A request can succeed even if - // a statement fails. The [ExecuteBatchDmlResponse.status][google.spanner.v1.ExecuteBatchDmlResponse.status] field in the - // response provides information about the statement that failed. Clients must - // inspect this field to determine whether an error occurred. + // a statement fails. The + // [ExecuteBatchDmlResponse.status][google.spanner.v1.ExecuteBatchDmlResponse.status] + // field in the response provides information about the statement that failed. + // Clients must inspect this field to determine whether an error occurred. // // Execution stops after the first failed statement; the remaining statements // are not executed. - rpc ExecuteBatchDml(ExecuteBatchDmlRequest) returns (ExecuteBatchDmlResponse) { + rpc ExecuteBatchDml(ExecuteBatchDmlRequest) + returns (ExecuteBatchDmlResponse) { option (google.api.http) = { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeBatchDml" body: "*" @@ -165,14 +178,15 @@ service Spanner { // Reads rows from the database using key lookups and scans, as a // simple key/value style alternative to - // [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. This method cannot be used to - // return a result set larger than 10 MiB; if the read matches more + // [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. This method cannot be + // used to return a result set larger than 10 MiB; if the read matches more // data than that, the read fails with a `FAILED_PRECONDITION` // error. // // Reads inside read-write transactions might return `ABORTED`. If // this occurs, the application should restart the transaction from - // the beginning. See [Transaction][google.spanner.v1.Transaction] for more details. + // the beginning. See [Transaction][google.spanner.v1.Transaction] for more + // details. // // Larger result sets can be yielded in streaming fashion by calling // [StreamingRead][google.spanner.v1.Spanner.StreamingRead] instead. @@ -183,9 +197,9 @@ service Spanner { }; } - // Like [Read][google.spanner.v1.Spanner.Read], except returns the result set as a - // stream. Unlike [Read][google.spanner.v1.Spanner.Read], there is no limit on the - // size of the returned result set. However, no individual row in + // Like [Read][google.spanner.v1.Spanner.Read], except returns the result set + // as a stream. Unlike [Read][google.spanner.v1.Spanner.Read], there is no + // limit on the size of the returned result set. However, no individual row in // the result set can exceed 100 MiB, and no column value can exceed // 10 MiB. rpc StreamingRead(ReadRequest) returns (stream PartialResultSet) { @@ -196,7 +210,8 @@ service Spanner { } // Begins a new transaction. This step can often be skipped: - // [Read][google.spanner.v1.Spanner.Read], [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] and + // [Read][google.spanner.v1.Spanner.Read], + // [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] and // [Commit][google.spanner.v1.Spanner.Commit] can begin a new transaction as a // side-effect. rpc BeginTransaction(BeginTransactionRequest) returns (Transaction) { @@ -221,13 +236,15 @@ service Spanner { body: "*" }; option (google.api.method_signature) = "session,transaction_id,mutations"; - option (google.api.method_signature) = "session,single_use_transaction,mutations"; + option (google.api.method_signature) = + "session,single_use_transaction,mutations"; } // Rolls back a transaction, releasing any locks it holds. It is a good // idea to call this for any transaction that includes one or more - // [Read][google.spanner.v1.Spanner.Read] or [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] requests and - // ultimately decides not to commit. + // [Read][google.spanner.v1.Spanner.Read] or + // [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] requests and ultimately + // decides not to commit. // // `Rollback` returns `OK` if it successfully aborts the transaction, the // transaction was already aborted, or the transaction is not @@ -242,10 +259,11 @@ service Spanner { // Creates a set of partition tokens that can be used to execute a query // operation in parallel. Each of the returned partition tokens can be used - // by [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] to specify a subset - // of the query result to read. The same session and read-only transaction - // must be used by the PartitionQueryRequest used to create the - // partition tokens and the ExecuteSqlRequests that use the partition tokens. + // by [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] to + // specify a subset of the query result to read. The same session and + // read-only transaction must be used by the PartitionQueryRequest used to + // create the partition tokens and the ExecuteSqlRequests that use the + // partition tokens. // // Partition tokens become invalid when the session used to create them // is deleted, is idle for too long, begins a new transaction, or becomes too @@ -260,12 +278,13 @@ service Spanner { // Creates a set of partition tokens that can be used to execute a read // operation in parallel. Each of the returned partition tokens can be used - // by [StreamingRead][google.spanner.v1.Spanner.StreamingRead] to specify a subset of the read - // result to read. The same session and read-only transaction must be used by - // the PartitionReadRequest used to create the partition tokens and the - // ReadRequests that use the partition tokens. There are no ordering - // guarantees on rows returned among the returned partition tokens, or even - // within each individual StreamingRead call issued with a partition_token. + // by [StreamingRead][google.spanner.v1.Spanner.StreamingRead] to specify a + // subset of the read result to read. The same session and read-only + // transaction must be used by the PartitionReadRequest used to create the + // partition tokens and the ReadRequests that use the partition tokens. There + // are no ordering guarantees on rows returned among the returned partition + // tokens, or even within each individual StreamingRead call issued with a + // partition_token. // // Partition tokens become invalid when the session used to create them // is deleted, is idle for too long, begins a new transaction, or becomes too @@ -293,7 +312,8 @@ message CreateSessionRequest { Session session = 2; } -// The request for [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions]. +// The request for +// [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions]. message BatchCreateSessionsRequest { // Required. The database in which the new sessions are created. string database = 1 [ @@ -310,11 +330,13 @@ message BatchCreateSessionsRequest { // The API may return fewer than the requested number of sessions. If a // specific number of sessions are desired, the client can make additional // calls to BatchCreateSessions (adjusting - // [session_count][google.spanner.v1.BatchCreateSessionsRequest.session_count] as necessary). + // [session_count][google.spanner.v1.BatchCreateSessionsRequest.session_count] + // as necessary). int32 session_count = 3 [(google.api.field_behavior) = REQUIRED]; } -// The response for [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions]. +// The response for +// [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions]. message BatchCreateSessionsResponse { // The freshly created sessions. repeated Session session = 1; @@ -355,9 +377,7 @@ message GetSessionRequest { // Required. The name of the session to retrieve. string name = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } + (google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } ]; } @@ -376,7 +396,8 @@ message ListSessionsRequest { int32 page_size = 2; // If non-empty, `page_token` should contain a - // [next_page_token][google.spanner.v1.ListSessionsResponse.next_page_token] from a previous + // [next_page_token][google.spanner.v1.ListSessionsResponse.next_page_token] + // from a previous // [ListSessionsResponse][google.spanner.v1.ListSessionsResponse]. string page_token = 3; @@ -399,8 +420,8 @@ message ListSessionsResponse { repeated Session sessions = 1; // `next_page_token` can be sent in a subsequent - // [ListSessions][google.spanner.v1.Spanner.ListSessions] call to fetch more of the matching - // sessions. + // [ListSessions][google.spanner.v1.Spanner.ListSessions] call to fetch more + // of the matching sessions. string next_page_token = 2; } @@ -409,9 +430,7 @@ message DeleteSessionRequest { // Required. The name of the session to delete. string name = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } + (google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } ]; } @@ -435,9 +454,7 @@ message ExecuteSqlRequest { // Required. The session in which the SQL query should be performed. string session = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } + (google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } ]; // The transaction to use. @@ -471,7 +488,8 @@ message ExecuteSqlRequest { // It is not always possible for Cloud Spanner to infer the right SQL type // from a JSON value. For example, values of type `BYTES` and values - // of type `STRING` both appear in [params][google.spanner.v1.ExecuteSqlRequest.params] as JSON strings. + // of type `STRING` both appear in + // [params][google.spanner.v1.ExecuteSqlRequest.params] as JSON strings. // // In these cases, `param_types` can be used to specify the exact // SQL type for some or all of the SQL statement parameters. See the @@ -481,15 +499,18 @@ message ExecuteSqlRequest { // If this request is resuming a previously interrupted SQL statement // execution, `resume_token` should be copied from the last - // [PartialResultSet][google.spanner.v1.PartialResultSet] yielded before the interruption. Doing this - // enables the new SQL statement execution to resume where the last one left - // off. The rest of the request parameters must exactly match the - // request that yielded this token. + // [PartialResultSet][google.spanner.v1.PartialResultSet] yielded before the + // interruption. Doing this enables the new SQL statement execution to resume + // where the last one left off. The rest of the request parameters must + // exactly match the request that yielded this token. bytes resume_token = 6; // Used to control the amount of debugging information returned in - // [ResultSetStats][google.spanner.v1.ResultSetStats]. If [partition_token][google.spanner.v1.ExecuteSqlRequest.partition_token] is set, [query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode] can only - // be set to [QueryMode.NORMAL][google.spanner.v1.ExecuteSqlRequest.QueryMode.NORMAL]. + // [ResultSetStats][google.spanner.v1.ResultSetStats]. If + // [partition_token][google.spanner.v1.ExecuteSqlRequest.partition_token] is + // set, [query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode] can only + // be set to + // [QueryMode.NORMAL][google.spanner.v1.ExecuteSqlRequest.QueryMode.NORMAL]. QueryMode query_mode = 7; // If present, results will be restricted to the specified partition @@ -534,7 +555,9 @@ message ExecuteBatchDmlRequest { // It is not always possible for Cloud Spanner to infer the right SQL type // from a JSON value. For example, values of type `BYTES` and values - // of type `STRING` both appear in [params][google.spanner.v1.ExecuteBatchDmlRequest.Statement.params] as JSON strings. + // of type `STRING` both appear in + // [params][google.spanner.v1.ExecuteBatchDmlRequest.Statement.params] as + // JSON strings. // // In these cases, `param_types` can be used to specify the exact // SQL type for some or all of the SQL statement parameters. See the @@ -546,9 +569,7 @@ message ExecuteBatchDmlRequest { // Required. The session in which the DML statements should be performed. string session = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } + (google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } ]; // Required. The transaction to use. Must be a read-write transaction. @@ -558,17 +579,17 @@ message ExecuteBatchDmlRequest { // transaction. TransactionSelector transaction = 2 [(google.api.field_behavior) = REQUIRED]; - // Required. The list of statements to execute in this batch. Statements are executed - // serially, such that the effects of statement `i` are visible to statement - // `i+1`. Each statement must be a DML statement. Execution stops at the - // first failed statement; the remaining statements are not executed. + // Required. The list of statements to execute in this batch. Statements are + // executed serially, such that the effects of statement `i` are visible to + // statement `i+1`. Each statement must be a DML statement. Execution stops at + // the first failed statement; the remaining statements are not executed. // // Callers must provide at least one statement. repeated Statement statements = 3 [(google.api.field_behavior) = REQUIRED]; - // Required. A per-transaction sequence number used to identify this request. This field - // makes each request idempotent such that if the request is received multiple - // times, at most one will succeed. + // Required. A per-transaction sequence number used to identify this request. + // This field makes each request idempotent such that if the request is + // received multiple times, at most one will succeed. // // The sequence number must be monotonically increasing within the // transaction. If a request arrives for the first time with an out-of-order @@ -577,38 +598,47 @@ message ExecuteBatchDmlRequest { int64 seqno = 4 [(google.api.field_behavior) = REQUIRED]; } -// The response for [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. Contains a list -// of [ResultSet][google.spanner.v1.ResultSet] messages, one for each DML statement that has successfully -// executed, in the same order as the statements in the request. If a statement -// fails, the status in the response body identifies the cause of the failure. +// The response for +// [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. Contains a list +// of [ResultSet][google.spanner.v1.ResultSet] messages, one for each DML +// statement that has successfully executed, in the same order as the statements +// in the request. If a statement fails, the status in the response body +// identifies the cause of the failure. // // To check for DML statements that failed, use the following approach: // -// 1. Check the status in the response message. The [google.rpc.Code][google.rpc.Code] enum +// 1. Check the status in the response message. The +// [google.rpc.Code][google.rpc.Code] enum // value `OK` indicates that all statements were executed successfully. // 2. If the status was not `OK`, check the number of result sets in the -// response. If the response contains `N` [ResultSet][google.spanner.v1.ResultSet] messages, then -// statement `N+1` in the request failed. +// response. If the response contains `N` +// [ResultSet][google.spanner.v1.ResultSet] messages, then statement `N+1` in +// the request failed. // // Example 1: // // * Request: 5 DML statements, all executed successfully. -// * Response: 5 [ResultSet][google.spanner.v1.ResultSet] messages, with the status `OK`. +// * Response: 5 [ResultSet][google.spanner.v1.ResultSet] messages, with the +// status `OK`. // // Example 2: // // * Request: 5 DML statements. The third statement has a syntax error. -// * Response: 2 [ResultSet][google.spanner.v1.ResultSet] messages, and a syntax error (`INVALID_ARGUMENT`) -// status. The number of [ResultSet][google.spanner.v1.ResultSet] messages indicates that the third -// statement failed, and the fourth and fifth statements were not executed. +// * Response: 2 [ResultSet][google.spanner.v1.ResultSet] messages, and a syntax +// error (`INVALID_ARGUMENT`) +// status. The number of [ResultSet][google.spanner.v1.ResultSet] messages +// indicates that the third statement failed, and the fourth and fifth +// statements were not executed. message ExecuteBatchDmlResponse { - // One [ResultSet][google.spanner.v1.ResultSet] for each statement in the request that ran successfully, - // in the same order as the statements in the request. Each [ResultSet][google.spanner.v1.ResultSet] does - // not contain any rows. The [ResultSetStats][google.spanner.v1.ResultSetStats] in each [ResultSet][google.spanner.v1.ResultSet] contain - // the number of rows modified by the statement. - // - // Only the first [ResultSet][google.spanner.v1.ResultSet] in the response contains valid - // [ResultSetMetadata][google.spanner.v1.ResultSetMetadata]. + // One [ResultSet][google.spanner.v1.ResultSet] for each statement in the + // request that ran successfully, in the same order as the statements in the + // request. Each [ResultSet][google.spanner.v1.ResultSet] does not contain any + // rows. The [ResultSetStats][google.spanner.v1.ResultSetStats] in each + // [ResultSet][google.spanner.v1.ResultSet] contain the number of rows + // modified by the statement. + // + // Only the first [ResultSet][google.spanner.v1.ResultSet] in the response + // contains valid [ResultSetMetadata][google.spanner.v1.ResultSetMetadata]. repeated ResultSet result_sets = 1; // If all DML statements are executed successfully, the status is `OK`. @@ -643,24 +673,23 @@ message PartitionQueryRequest { // Required. The session used to create the partitions. string session = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } + (google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } ]; // Read only snapshot transactions are supported, read/write and single use // transactions are not. TransactionSelector transaction = 2; - // Required. The query request to generate partitions for. The request will fail if - // the query is not root partitionable. The query plan of a root + // Required. The query request to generate partitions for. The request will + // fail if the query is not root partitionable. The query plan of a root // partitionable query has a single distributed union operator. A distributed // union operator conceptually divides one or more tables into multiple // splits, remotely evaluates a subquery independently on each split, and // then unions all results. // // This must not contain DML commands, such as INSERT, UPDATE, or - // DELETE. Use [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] with a + // DELETE. Use + // [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] with a // PartitionedDml transaction for large, partition-friendly DML operations. string sql = 3 [(google.api.field_behavior) = REQUIRED]; @@ -680,7 +709,8 @@ message PartitionQueryRequest { // It is not always possible for Cloud Spanner to infer the right SQL type // from a JSON value. For example, values of type `BYTES` and values - // of type `STRING` both appear in [params][google.spanner.v1.PartitionQueryRequest.params] as JSON strings. + // of type `STRING` both appear in + // [params][google.spanner.v1.PartitionQueryRequest.params] as JSON strings. // // In these cases, `param_types` can be used to specify the exact // SQL type for some or all of the SQL query parameters. See the @@ -697,9 +727,7 @@ message PartitionReadRequest { // Required. The session used to create the partitions. string session = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } + (google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } ]; // Read only snapshot transactions are supported, read/write and single use @@ -709,18 +737,24 @@ message PartitionReadRequest { // Required. The name of the table in the database to be read. string table = 3 [(google.api.field_behavior) = REQUIRED]; - // If non-empty, the name of an index on [table][google.spanner.v1.PartitionReadRequest.table]. This index is - // used instead of the table primary key when interpreting [key_set][google.spanner.v1.PartitionReadRequest.key_set] - // and sorting result rows. See [key_set][google.spanner.v1.PartitionReadRequest.key_set] for further information. + // If non-empty, the name of an index on + // [table][google.spanner.v1.PartitionReadRequest.table]. This index is used + // instead of the table primary key when interpreting + // [key_set][google.spanner.v1.PartitionReadRequest.key_set] and sorting + // result rows. See [key_set][google.spanner.v1.PartitionReadRequest.key_set] + // for further information. string index = 4; - // The columns of [table][google.spanner.v1.PartitionReadRequest.table] to be returned for each row matching - // this request. + // The columns of [table][google.spanner.v1.PartitionReadRequest.table] to be + // returned for each row matching this request. repeated string columns = 5; // Required. `key_set` identifies the rows to be yielded. `key_set` names the - // primary keys of the rows in [table][google.spanner.v1.PartitionReadRequest.table] to be yielded, unless [index][google.spanner.v1.PartitionReadRequest.index] - // is present. If [index][google.spanner.v1.PartitionReadRequest.index] is present, then [key_set][google.spanner.v1.PartitionReadRequest.key_set] instead names + // primary keys of the rows in + // [table][google.spanner.v1.PartitionReadRequest.table] to be yielded, unless + // [index][google.spanner.v1.PartitionReadRequest.index] is present. If + // [index][google.spanner.v1.PartitionReadRequest.index] is present, then + // [key_set][google.spanner.v1.PartitionReadRequest.key_set] instead names // index keys in [index][google.spanner.v1.PartitionReadRequest.index]. // // It is not an error for the `key_set` to name rows that do not @@ -756,9 +790,7 @@ message ReadRequest { // Required. The session in which the read should be performed. string session = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } + (google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } ]; // The transaction to use. If none is provided, the default is a @@ -768,24 +800,31 @@ message ReadRequest { // Required. The name of the table in the database to be read. string table = 3 [(google.api.field_behavior) = REQUIRED]; - // If non-empty, the name of an index on [table][google.spanner.v1.ReadRequest.table]. This index is - // used instead of the table primary key when interpreting [key_set][google.spanner.v1.ReadRequest.key_set] - // and sorting result rows. See [key_set][google.spanner.v1.ReadRequest.key_set] for further information. + // If non-empty, the name of an index on + // [table][google.spanner.v1.ReadRequest.table]. This index is used instead of + // the table primary key when interpreting + // [key_set][google.spanner.v1.ReadRequest.key_set] and sorting result rows. + // See [key_set][google.spanner.v1.ReadRequest.key_set] for further + // information. string index = 4; - // Required. The columns of [table][google.spanner.v1.ReadRequest.table] to be returned for each row matching - // this request. + // Required. The columns of [table][google.spanner.v1.ReadRequest.table] to be + // returned for each row matching this request. repeated string columns = 5 [(google.api.field_behavior) = REQUIRED]; // Required. `key_set` identifies the rows to be yielded. `key_set` names the - // primary keys of the rows in [table][google.spanner.v1.ReadRequest.table] to be yielded, unless [index][google.spanner.v1.ReadRequest.index] - // is present. If [index][google.spanner.v1.ReadRequest.index] is present, then [key_set][google.spanner.v1.ReadRequest.key_set] instead names - // index keys in [index][google.spanner.v1.ReadRequest.index]. - // - // If the [partition_token][google.spanner.v1.ReadRequest.partition_token] field is empty, rows are yielded - // in table primary key order (if [index][google.spanner.v1.ReadRequest.index] is empty) or index key order - // (if [index][google.spanner.v1.ReadRequest.index] is non-empty). If the [partition_token][google.spanner.v1.ReadRequest.partition_token] field is not - // empty, rows will be yielded in an unspecified order. + // primary keys of the rows in [table][google.spanner.v1.ReadRequest.table] to + // be yielded, unless [index][google.spanner.v1.ReadRequest.index] is present. + // If [index][google.spanner.v1.ReadRequest.index] is present, then + // [key_set][google.spanner.v1.ReadRequest.key_set] instead names index keys + // in [index][google.spanner.v1.ReadRequest.index]. + // + // If the [partition_token][google.spanner.v1.ReadRequest.partition_token] + // field is empty, rows are yielded in table primary key order (if + // [index][google.spanner.v1.ReadRequest.index] is empty) or index key order + // (if [index][google.spanner.v1.ReadRequest.index] is non-empty). If the + // [partition_token][google.spanner.v1.ReadRequest.partition_token] field is + // not empty, rows will be yielded in an unspecified order. // // It is not an error for the `key_set` to name rows that do not // exist in the database. Read yields nothing for nonexistent rows. @@ -798,9 +837,9 @@ message ReadRequest { // If this request is resuming a previously interrupted read, // `resume_token` should be copied from the last - // [PartialResultSet][google.spanner.v1.PartialResultSet] yielded before the interruption. Doing this - // enables the new read to resume where the last read left off. The - // rest of the request parameters must exactly match the request + // [PartialResultSet][google.spanner.v1.PartialResultSet] yielded before the + // interruption. Doing this enables the new read to resume where the last read + // left off. The rest of the request parameters must exactly match the request // that yielded this token. bytes resume_token = 9; @@ -811,14 +850,13 @@ message ReadRequest { bytes partition_token = 10; } -// The request for [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction]. +// The request for +// [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction]. message BeginTransactionRequest { // Required. The session in which the transaction runs. string session = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } + (google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } ]; // Required. Options for the new transaction. @@ -830,9 +868,7 @@ message CommitRequest { // Required. The session in which the transaction to be committed is running. string session = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } + (google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } ]; // Required. The transaction in which to commit. @@ -869,19 +905,9 @@ message RollbackRequest { // Required. The session in which the transaction to roll back is running. string session = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } + (google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } ]; // Required. The transaction to roll back. bytes transaction_id = 2 [(google.api.field_behavior) = REQUIRED]; } - -// The Database resource is defined in `google.spanner.admin.database.v1`. -// Because this is a separate, independent API (technically), we redefine -// the resource name pattern here. -option (google.api.resource_definition) = { - type: "spanner.googleapis.com/Database" - pattern: "projects/{project}/instances/{instance}/databases/{database}" -}; diff --git a/google/cloud/spanner_v1/proto/spanner_pb2_grpc.py b/google/cloud/spanner_v1/proto/spanner_pb2_grpc.py index 266d7bdc61..4505b75cbc 100644 --- a/google/cloud/spanner_v1/proto/spanner_pb2_grpc.py +++ b/google/cloud/spanner_v1/proto/spanner_pb2_grpc.py @@ -178,21 +178,23 @@ def ExecuteSql(self, request, context): Operations inside read-write transactions might return `ABORTED`. If this occurs, the application should restart the transaction from - the beginning. See [Transaction][google.spanner.v1.Transaction] for more details. + the beginning. See [Transaction][google.spanner.v1.Transaction] for more + details. Larger result sets can be fetched in streaming fashion by calling - [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] instead. + [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] + instead. """ context.set_code(grpc.StatusCode.UNIMPLEMENTED) context.set_details("Method not implemented!") raise NotImplementedError("Method not implemented!") def ExecuteStreamingSql(self, request, context): - """Like [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], except returns the result - set as a stream. Unlike [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], there - is no limit on the size of the returned result set. However, no - individual row in the result set can exceed 100 MiB, and no - column value can exceed 10 MiB. + """Like [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], except returns the + result set as a stream. Unlike + [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], there is no limit on + the size of the returned result set. However, no individual row in the + result set can exceed 100 MiB, and no column value can exceed 10 MiB. """ context.set_code(grpc.StatusCode.UNIMPLEMENTED) context.set_details("Method not implemented!") @@ -204,9 +206,10 @@ def ExecuteBatchDml(self, request, context): [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. Statements are executed in sequential order. A request can succeed even if - a statement fails. The [ExecuteBatchDmlResponse.status][google.spanner.v1.ExecuteBatchDmlResponse.status] field in the - response provides information about the statement that failed. Clients must - inspect this field to determine whether an error occurred. + a statement fails. The + [ExecuteBatchDmlResponse.status][google.spanner.v1.ExecuteBatchDmlResponse.status] + field in the response provides information about the statement that failed. + Clients must inspect this field to determine whether an error occurred. Execution stops after the first failed statement; the remaining statements are not executed. @@ -218,14 +221,15 @@ def ExecuteBatchDml(self, request, context): def Read(self, request, context): """Reads rows from the database using key lookups and scans, as a simple key/value style alternative to - [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. This method cannot be used to - return a result set larger than 10 MiB; if the read matches more + [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. This method cannot be + used to return a result set larger than 10 MiB; if the read matches more data than that, the read fails with a `FAILED_PRECONDITION` error. Reads inside read-write transactions might return `ABORTED`. If this occurs, the application should restart the transaction from - the beginning. See [Transaction][google.spanner.v1.Transaction] for more details. + the beginning. See [Transaction][google.spanner.v1.Transaction] for more + details. Larger result sets can be yielded in streaming fashion by calling [StreamingRead][google.spanner.v1.Spanner.StreamingRead] instead. @@ -235,9 +239,9 @@ def Read(self, request, context): raise NotImplementedError("Method not implemented!") def StreamingRead(self, request, context): - """Like [Read][google.spanner.v1.Spanner.Read], except returns the result set as a - stream. Unlike [Read][google.spanner.v1.Spanner.Read], there is no limit on the - size of the returned result set. However, no individual row in + """Like [Read][google.spanner.v1.Spanner.Read], except returns the result set + as a stream. Unlike [Read][google.spanner.v1.Spanner.Read], there is no + limit on the size of the returned result set. However, no individual row in the result set can exceed 100 MiB, and no column value can exceed 10 MiB. """ @@ -247,7 +251,8 @@ def StreamingRead(self, request, context): def BeginTransaction(self, request, context): """Begins a new transaction. This step can often be skipped: - [Read][google.spanner.v1.Spanner.Read], [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] and + [Read][google.spanner.v1.Spanner.Read], + [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] and [Commit][google.spanner.v1.Spanner.Commit] can begin a new transaction as a side-effect. """ @@ -272,8 +277,9 @@ def Commit(self, request, context): def Rollback(self, request, context): """Rolls back a transaction, releasing any locks it holds. It is a good idea to call this for any transaction that includes one or more - [Read][google.spanner.v1.Spanner.Read] or [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] requests and - ultimately decides not to commit. + [Read][google.spanner.v1.Spanner.Read] or + [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] requests and ultimately + decides not to commit. `Rollback` returns `OK` if it successfully aborts the transaction, the transaction was already aborted, or the transaction is not @@ -286,10 +292,11 @@ def Rollback(self, request, context): def PartitionQuery(self, request, context): """Creates a set of partition tokens that can be used to execute a query operation in parallel. Each of the returned partition tokens can be used - by [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] to specify a subset - of the query result to read. The same session and read-only transaction - must be used by the PartitionQueryRequest used to create the - partition tokens and the ExecuteSqlRequests that use the partition tokens. + by [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] to + specify a subset of the query result to read. The same session and + read-only transaction must be used by the PartitionQueryRequest used to + create the partition tokens and the ExecuteSqlRequests that use the + partition tokens. Partition tokens become invalid when the session used to create them is deleted, is idle for too long, begins a new transaction, or becomes too @@ -303,12 +310,13 @@ def PartitionQuery(self, request, context): def PartitionRead(self, request, context): """Creates a set of partition tokens that can be used to execute a read operation in parallel. Each of the returned partition tokens can be used - by [StreamingRead][google.spanner.v1.Spanner.StreamingRead] to specify a subset of the read - result to read. The same session and read-only transaction must be used by - the PartitionReadRequest used to create the partition tokens and the - ReadRequests that use the partition tokens. There are no ordering - guarantees on rows returned among the returned partition tokens, or even - within each individual StreamingRead call issued with a partition_token. + by [StreamingRead][google.spanner.v1.Spanner.StreamingRead] to specify a + subset of the read result to read. The same session and read-only + transaction must be used by the PartitionReadRequest used to create the + partition tokens and the ReadRequests that use the partition tokens. There + are no ordering guarantees on rows returned among the returned partition + tokens, or even within each individual StreamingRead call issued with a + partition_token. Partition tokens become invalid when the session used to create them is deleted, is idle for too long, begins a new transaction, or becomes too diff --git a/google/cloud/spanner_v1/transaction.py b/google/cloud/spanner_v1/transaction.py index b4eb21143a..29a2e5f786 100644 --- a/google/cloud/spanner_v1/transaction.py +++ b/google/cloud/spanner_v1/transaction.py @@ -122,7 +122,7 @@ def commit(self): metadata = _metadata_with_prefix(database.name) response = api.commit( self._session.name, - self._mutations, + mutations=self._mutations, transaction_id=self._transaction_id, metadata=metadata, ) diff --git a/synth.metadata b/synth.metadata index b79fe4dbbe..3cd01cf197 100644 --- a/synth.metadata +++ b/synth.metadata @@ -1,26 +1,26 @@ { - "updateTime": "2019-10-31T15:04:36.072689Z", + "updateTime": "2019-12-24T03:07:53.081048Z", "sources": [ { "generator": { "name": "artman", - "version": "0.41.0", - "dockerImage": "googleapis/artman@sha256:75b38a3b073a7b243545f2332463096624c802bb1e56b8cb6f22ba1ecd325fa9" + "version": "0.42.3", + "dockerImage": "googleapis/artman@sha256:feed210b5723c6f524b52ef6d7740a030f2d1a8f7c29a71c5e5b4481ceaad7f5" } }, { "git": { "name": "googleapis", "remote": "https://github.com/googleapis/googleapis.git", - "sha": "c0e494ca955a4fdd9ad460a5890a354ec3a3a0ff", - "internalRef": "277673798" + "sha": "46e52fd64973e815cae61e78b14608fe7aa7b1df", + "internalRef": "286958627" } }, { "template": { "name": "python_library", "origin": "synthtool.gcp", - "version": "2019.5.2" + "version": "2019.10.17" } } ], diff --git a/tests/unit/gapic/v1/test_database_admin_client_v1.py b/tests/unit/gapic/v1/test_database_admin_client_v1.py index 166e823b37..7d5da4a18b 100644 --- a/tests/unit/gapic/v1/test_database_admin_client_v1.py +++ b/tests/unit/gapic/v1/test_database_admin_client_v1.py @@ -66,53 +66,6 @@ class CustomException(Exception): class TestDatabaseAdminClient(object): - def test_list_databases(self): - # Setup Expected Response - next_page_token = "" - databases_element = {} - databases = [databases_element] - expected_response = {"next_page_token": next_page_token, "databases": databases} - expected_response = spanner_database_admin_pb2.ListDatabasesResponse( - **expected_response - ) - - # Mock the API response - channel = ChannelStub(responses=[expected_response]) - patch = mock.patch("google.api_core.grpc_helpers.create_channel") - with patch as create_channel: - create_channel.return_value = channel - client = spanner_admin_database_v1.DatabaseAdminClient() - - # Setup Request - parent = client.instance_path("[PROJECT]", "[INSTANCE]") - - paged_list_response = client.list_databases(parent) - resources = list(paged_list_response) - assert len(resources) == 1 - - assert expected_response.databases[0] == resources[0] - - assert len(channel.requests) == 1 - expected_request = spanner_database_admin_pb2.ListDatabasesRequest( - parent=parent - ) - actual_request = channel.requests[0][1] - assert expected_request == actual_request - - def test_list_databases_exception(self): - channel = ChannelStub(responses=[CustomException()]) - patch = mock.patch("google.api_core.grpc_helpers.create_channel") - with patch as create_channel: - create_channel.return_value = channel - client = spanner_admin_database_v1.DatabaseAdminClient() - - # Setup request - parent = client.instance_path("[PROJECT]", "[INSTANCE]") - - paged_list_response = client.list_databases(parent) - with pytest.raises(CustomException): - list(paged_list_response) - def test_create_database(self): # Setup Expected Response name = "name3373707" @@ -349,7 +302,7 @@ def test_set_iam_policy(self): client = spanner_admin_database_v1.DatabaseAdminClient() # Setup Request - resource = client.database_path("[PROJECT]", "[INSTANCE]", "[DATABASE]") + resource = "resource-341064690" policy = {} response = client.set_iam_policy(resource, policy) @@ -371,7 +324,7 @@ def test_set_iam_policy_exception(self): client = spanner_admin_database_v1.DatabaseAdminClient() # Setup request - resource = client.database_path("[PROJECT]", "[INSTANCE]", "[DATABASE]") + resource = "resource-341064690" policy = {} with pytest.raises(CustomException): @@ -392,7 +345,7 @@ def test_get_iam_policy(self): client = spanner_admin_database_v1.DatabaseAdminClient() # Setup Request - resource = client.database_path("[PROJECT]", "[INSTANCE]", "[DATABASE]") + resource = "resource-341064690" response = client.get_iam_policy(resource) assert expected_response == response @@ -411,7 +364,7 @@ def test_get_iam_policy_exception(self): client = spanner_admin_database_v1.DatabaseAdminClient() # Setup request - resource = client.database_path("[PROJECT]", "[INSTANCE]", "[DATABASE]") + resource = "resource-341064690" with pytest.raises(CustomException): client.get_iam_policy(resource) @@ -431,7 +384,7 @@ def test_test_iam_permissions(self): client = spanner_admin_database_v1.DatabaseAdminClient() # Setup Request - resource = client.database_path("[PROJECT]", "[INSTANCE]", "[DATABASE]") + resource = "resource-341064690" permissions = [] response = client.test_iam_permissions(resource, permissions) @@ -453,8 +406,55 @@ def test_test_iam_permissions_exception(self): client = spanner_admin_database_v1.DatabaseAdminClient() # Setup request - resource = client.database_path("[PROJECT]", "[INSTANCE]", "[DATABASE]") + resource = "resource-341064690" permissions = [] with pytest.raises(CustomException): client.test_iam_permissions(resource, permissions) + + def test_list_databases(self): + # Setup Expected Response + next_page_token = "" + databases_element = {} + databases = [databases_element] + expected_response = {"next_page_token": next_page_token, "databases": databases} + expected_response = spanner_database_admin_pb2.ListDatabasesResponse( + **expected_response + ) + + # Mock the API response + channel = ChannelStub(responses=[expected_response]) + patch = mock.patch("google.api_core.grpc_helpers.create_channel") + with patch as create_channel: + create_channel.return_value = channel + client = spanner_admin_database_v1.DatabaseAdminClient() + + # Setup Request + parent = client.instance_path("[PROJECT]", "[INSTANCE]") + + paged_list_response = client.list_databases(parent) + resources = list(paged_list_response) + assert len(resources) == 1 + + assert expected_response.databases[0] == resources[0] + + assert len(channel.requests) == 1 + expected_request = spanner_database_admin_pb2.ListDatabasesRequest( + parent=parent + ) + actual_request = channel.requests[0][1] + assert expected_request == actual_request + + def test_list_databases_exception(self): + channel = ChannelStub(responses=[CustomException()]) + patch = mock.patch("google.api_core.grpc_helpers.create_channel") + with patch as create_channel: + create_channel.return_value = channel + client = spanner_admin_database_v1.DatabaseAdminClient() + + # Setup request + parent = client.instance_path("[PROJECT]", "[INSTANCE]") + + paged_list_response = client.list_databases(parent) + with pytest.raises(CustomException): + list(paged_list_response) diff --git a/tests/unit/gapic/v1/test_instance_admin_client_v1.py b/tests/unit/gapic/v1/test_instance_admin_client_v1.py index 60f63938f9..f535723f98 100644 --- a/tests/unit/gapic/v1/test_instance_admin_client_v1.py +++ b/tests/unit/gapic/v1/test_instance_admin_client_v1.py @@ -427,7 +427,7 @@ def test_set_iam_policy(self): client = spanner_admin_instance_v1.InstanceAdminClient() # Setup Request - resource = client.instance_path("[PROJECT]", "[INSTANCE]") + resource = "resource-341064690" policy = {} response = client.set_iam_policy(resource, policy) @@ -449,7 +449,7 @@ def test_set_iam_policy_exception(self): client = spanner_admin_instance_v1.InstanceAdminClient() # Setup request - resource = client.instance_path("[PROJECT]", "[INSTANCE]") + resource = "resource-341064690" policy = {} with pytest.raises(CustomException): @@ -470,7 +470,7 @@ def test_get_iam_policy(self): client = spanner_admin_instance_v1.InstanceAdminClient() # Setup Request - resource = client.instance_path("[PROJECT]", "[INSTANCE]") + resource = "resource-341064690" response = client.get_iam_policy(resource) assert expected_response == response @@ -489,7 +489,7 @@ def test_get_iam_policy_exception(self): client = spanner_admin_instance_v1.InstanceAdminClient() # Setup request - resource = client.instance_path("[PROJECT]", "[INSTANCE]") + resource = "resource-341064690" with pytest.raises(CustomException): client.get_iam_policy(resource) @@ -509,7 +509,7 @@ def test_test_iam_permissions(self): client = spanner_admin_instance_v1.InstanceAdminClient() # Setup Request - resource = client.instance_path("[PROJECT]", "[INSTANCE]") + resource = "resource-341064690" permissions = [] response = client.test_iam_permissions(resource, permissions) @@ -531,7 +531,7 @@ def test_test_iam_permissions_exception(self): client = spanner_admin_instance_v1.InstanceAdminClient() # Setup request - resource = client.instance_path("[PROJECT]", "[INSTANCE]") + resource = "resource-341064690" permissions = [] with pytest.raises(CustomException): diff --git a/tests/unit/gapic/v1/test_spanner_client_v1.py b/tests/unit/gapic/v1/test_spanner_client_v1.py index 55610ee409..9f63d09673 100644 --- a/tests/unit/gapic/v1/test_spanner_client_v1.py +++ b/tests/unit/gapic/v1/test_spanner_client_v1.py @@ -567,15 +567,12 @@ def test_commit(self): session = client.session_path( "[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]" ) - mutations = [] - response = client.commit(session, mutations) + response = client.commit(session) assert expected_response == response assert len(channel.requests) == 1 - expected_request = spanner_pb2.CommitRequest( - session=session, mutations=mutations - ) + expected_request = spanner_pb2.CommitRequest(session=session) actual_request = channel.requests[0][1] assert expected_request == actual_request @@ -591,10 +588,9 @@ def test_commit_exception(self): session = client.session_path( "[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]" ) - mutations = [] with pytest.raises(CustomException): - client.commit(session, mutations) + client.commit(session) def test_rollback(self): channel = ChannelStub() diff --git a/tests/unit/test_database.py b/tests/unit/test_database.py index f6f367e001..163036f030 100644 --- a/tests/unit/test_database.py +++ b/tests/unit/test_database.py @@ -967,7 +967,7 @@ def test_context_mgr_success(self): api.commit.assert_called_once_with( self.SESSION_NAME, - [], + mutations=[], single_use_transaction=expected_txn_options, metadata=[("google-cloud-resource-prefix", database.name)], ) diff --git a/tests/unit/test_session.py b/tests/unit/test_session.py index a198d19ecd..98d98deaba 100644 --- a/tests/unit/test_session.py +++ b/tests/unit/test_session.py @@ -628,7 +628,7 @@ def unit_of_work(txn, *args, **kw): ) gax_api.commit.assert_called_once_with( self.SESSION_NAME, - txn._mutations, + mutations=txn._mutations, transaction_id=TRANSACTION_ID, metadata=[("google-cloud-resource-prefix", database.name)], ) @@ -675,7 +675,7 @@ def unit_of_work(txn, *args, **kw): gax_api.begin_transaction.assert_not_called() gax_api.commit.assert_called_once_with( self.SESSION_NAME, - txn._mutations, + mutations=txn._mutations, transaction_id=TRANSACTION_ID, metadata=[("google-cloud-resource-prefix", database.name)], ) @@ -745,7 +745,7 @@ def unit_of_work(txn, *args, **kw): [ mock.call( self.SESSION_NAME, - txn._mutations, + mutations=txn._mutations, transaction_id=TRANSACTION_ID, metadata=[("google-cloud-resource-prefix", database.name)], ) @@ -833,7 +833,7 @@ def unit_of_work(txn, *args, **kw): [ mock.call( self.SESSION_NAME, - txn._mutations, + mutations=txn._mutations, transaction_id=TRANSACTION_ID, metadata=[("google-cloud-resource-prefix", database.name)], ) @@ -918,7 +918,7 @@ def unit_of_work(txn, *args, **kw): ) gax_api.commit.assert_called_once_with( self.SESSION_NAME, - txn._mutations, + mutations=txn._mutations, transaction_id=TRANSACTION_ID, metadata=[("google-cloud-resource-prefix", database.name)], ) @@ -997,7 +997,7 @@ def _time(_results=[1, 1.5]): ) gax_api.commit.assert_called_once_with( self.SESSION_NAME, - txn._mutations, + mutations=txn._mutations, transaction_id=TRANSACTION_ID, metadata=[("google-cloud-resource-prefix", database.name)], ) @@ -1072,7 +1072,7 @@ def _time(_results=[1, 2, 4, 8]): [ mock.call( self.SESSION_NAME, - txn._mutations, + mutations=txn._mutations, transaction_id=TRANSACTION_ID, metadata=[("google-cloud-resource-prefix", database.name)], )