Spanner: Add batch_create_sessions (via synth).

spanner/google/cloud/spanner_v1/gapic/spanner_client.py

@@ -307,6 +307,92 @@ def create_session(
             request, retry=retry, timeout=timeout, metadata=metadata
         )
 
+    def batch_create_sessions(
+        self,
+        database,
+        session_template=None,
+        session_count=None,
+        retry=google.api_core.gapic_v1.method.DEFAULT,
+        timeout=google.api_core.gapic_v1.method.DEFAULT,
+        metadata=None,
+    ):
+        """
+        Creates multiple new sessions.
+
+        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.
+
+        Example:
+            >>> from google.cloud import spanner_v1
+            >>>
+            >>> client = spanner_v1.SpannerClient()
+            >>>
+            >>> database = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]')
+            >>>
+            >>> response = client.batch_create_sessions(database)
+
+        Args:
+            database (str): Required. The database in which the new sessions are created.
+            session_template (Union[dict, ~google.cloud.spanner_v1.types.Session]): Parameters to be applied to each created session.
+
+                If a dict is provided, it must be of the same form as the protobuf
+                message :class:`~google.cloud.spanner_v1.types.Session`
+            session_count (int): Required. The number of sessions to be created in this batch call. 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`` as necessary).
+            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.cloud.spanner_v1.types.BatchCreateSessionsResponse` instance.
+
+        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 "batch_create_sessions" not in self._inner_api_calls:
+            self._inner_api_calls[
+                "batch_create_sessions"
+            ] = google.api_core.gapic_v1.method.wrap_method(
+                self.transport.batch_create_sessions,
+                default_retry=self._method_configs["BatchCreateSessions"].retry,
+                default_timeout=self._method_configs["BatchCreateSessions"].timeout,
+                client_info=self._client_info,
+            )
+
+        request = spanner_pb2.BatchCreateSessionsRequest(
+            database=database,
+            session_template=session_template,
+            session_count=session_count,
+        )
+        if metadata is None:
+            metadata = []
+        metadata = list(metadata)
+        try:
+            routing_header = [("database", database)]
+        except AttributeError:
+            pass
+        else:
+            routing_metadata = google.api_core.gapic_v1.routing_header.to_grpc_metadata(
+                routing_header
+            )
+            metadata.append(routing_metadata)
+
+        return self._inner_api_calls["batch_create_sessions"](
+            request, retry=retry, timeout=timeout, metadata=metadata
+        )
+
     def get_session(
         self,
         name,
@@ -602,10 +688,7 @@ def execute_sql(
         Args:
             session (str): Required. The session in which the SQL query should be performed.
             sql (str): Required. The SQL string.
-            transaction (Union[dict, ~google.cloud.spanner_v1.types.TransactionSelector]): The transaction to use. If none is provided, the default is a
-                temporary read-only transaction with strong concurrency.
-
-                The transaction to use.
+            transaction (Union[dict, ~google.cloud.spanner_v1.types.TransactionSelector]): The transaction to use.
 
                 For queries, if none is provided, the default is a temporary read-only
                 transaction with strong concurrency.
@@ -764,10 +847,7 @@ def execute_streaming_sql(
         Args:
             session (str): Required. The session in which the SQL query should be performed.
             sql (str): Required. The SQL string.
-            transaction (Union[dict, ~google.cloud.spanner_v1.types.TransactionSelector]): The transaction to use. If none is provided, the default is a
-                temporary read-only transaction with strong concurrency.
-
-                The transaction to use.
+            transaction (Union[dict, ~google.cloud.spanner_v1.types.TransactionSelector]): The transaction to use.
 
                 For queries, if none is provided, the default is a temporary read-only
                 transaction with strong concurrency.

spanner/google/cloud/spanner_v1/gapic/spanner_client_config.py

@@ -41,6 +41,11 @@
                     "retry_codes_name": "idempotent",
                     "retry_params_name": "default",
                 },
+                "BatchCreateSessions": {
+                    "timeout_millis": 60000,
+                    "retry_codes_name": "idempotent",
+                    "retry_params_name": "default",
+                },
                 "GetSession": {
                     "timeout_millis": 30000,
                     "retry_codes_name": "idempotent",

spanner/google/cloud/spanner_v1/gapic/transports/spanner_grpc_transport.py

@@ -147,6 +147,22 @@ def create_session(self):
         """
         return self._stubs["spanner_stub"].CreateSession
 
+    @property
+    def batch_create_sessions(self):
+        """Return the gRPC stub for :meth:`SpannerClient.batch_create_sessions`.
+
+        Creates multiple new sessions.
+
+        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.
+
+        Returns:
+            Callable: A callable which accepts the appropriate
+                deserialized request object and returns a
+                deserialized response object.
+        """
+        return self._stubs["spanner_stub"].BatchCreateSessions
+
     @property
     def get_session(self):
         """Return the gRPC stub for :meth:`SpannerClient.get_session`.

spanner/google/cloud/spanner_v1/proto/spanner.proto

@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC.
+// Copyright 2019 Google LLC.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -66,6 +66,18 @@ service Spanner {
     };
   }
 
+  // Creates multiple new sessions.
+  //
+  // 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) {
+    option (google.api.http) = {
+      post: "/v1/{database=projects/*/instances/*/databases/*}/sessions:batchCreate"
+      body: "*"
+    };
+  }
+
   // Gets a session. Returns `NOT_FOUND` if the session does not exist.
   // This is mainly useful for determining whether a session is still
   // alive.
@@ -129,8 +141,9 @@ service Spanner {
   //
   // Statements are executed in order, sequentially.
   // [ExecuteBatchDmlResponse][Spanner.ExecuteBatchDmlResponse] will contain a
-  // [ResultSet][google.spanner.v1.ResultSet] for each DML statement that has successfully executed. If a
-  // statement fails, its error status will be returned as part of the
+  // [ResultSet][google.spanner.v1.ResultSet] for each DML statement that has
+  // successfully executed. If a statement fails, its error status will be
+  // returned as part of the
   // [ExecuteBatchDmlResponse][Spanner.ExecuteBatchDmlResponse]. Execution will
   // stop at the first failed statement; the remaining statements will not run.
   //
@@ -142,7 +155,8 @@ service Spanner {
   // See more details in
   // [ExecuteBatchDmlRequest][Spanner.ExecuteBatchDmlRequest] and
   // [ExecuteBatchDmlResponse][Spanner.ExecuteBatchDmlResponse].
-  rpc ExecuteBatchDml(ExecuteBatchDmlRequest) returns (ExecuteBatchDmlResponse) {
+  rpc ExecuteBatchDml(ExecuteBatchDmlRequest)
+      returns (ExecuteBatchDmlResponse) {
     option (google.api.http) = {
       post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeBatchDml"
       body: "*"
@@ -275,6 +289,31 @@ message CreateSessionRequest {
   Session session = 2;
 }
 
+// The request for
+// [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions].
+message BatchCreateSessionsRequest {
+  // Required. The database in which the new sessions are created.
+  string database = 1;
+
+  // Parameters to be applied to each created session.
+  Session session_template = 2;
+
+  // Required. The number of sessions to be created in this batch call.
+  // 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).
+  int32 session_count = 3;
+}
+
+// The response for
+// [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions].
+message BatchCreateSessionsResponse {
+  // The freshly created sessions.
+  repeated Session session = 1;
+}
+
 // A session in the Cloud Spanner API.
 message Session {
   // The name of the session. This is always system-assigned; values provided
@@ -371,9 +410,6 @@ message ExecuteSqlRequest {
   // Required. The session in which the SQL query should be performed.
   string session = 1;
 
-  // The transaction to use. If none is provided, the default is a
-  // temporary read-only transaction with strong concurrency.
-  //
   // The transaction to use.
   //
   // For queries, if none is provided, the default is a temporary read-only
@@ -476,7 +512,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
@@ -508,11 +546,13 @@ message ExecuteBatchDmlRequest {
   int64 seqno = 4;
 }
 
-// The response for [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. Contains a list
-// of [ResultSet][google.spanner.v1.ResultSet], one for each DML statement that has successfully executed.
-// If a statement fails, the error is returned as part of the response payload.
-// Clients can determine whether all DML statements have run successfully, or if
-// a statement failed, using one of the following approaches:
+// The response for
+// [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. Contains a list
+// of [ResultSet][google.spanner.v1.ResultSet], one for each DML statement that
+// has successfully executed. If a statement fails, the error is returned as
+// part of the response payload. Clients can determine whether all DML
+// statements have run successfully, or if a statement failed, using one of the
+// following approaches:
 //
 //   1. Check if 'status' field is OkStatus.
 //   2. Check if result_sets_size() equals the number of statements in
@@ -529,9 +569,11 @@ message ExecuteBatchDmlRequest {
 // result_set_size() client can determine that the 3rd statement has failed.
 message ExecuteBatchDmlResponse {
   // ResultSets, one 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] will
-  // not contain any rows. The [ResultSetStats][google.spanner.v1.ResultSetStats] in each [ResultSet][google.spanner.v1.ResultSet] will
-  // contain the number of rows modified by the statement.
+  // the same order as the statements in the request. Each
+  // [ResultSet][google.spanner.v1.ResultSet] will not contain any rows. The
+  // [ResultSetStats][google.spanner.v1.ResultSetStats] in each
+  // [ResultSet][google.spanner.v1.ResultSet] will contain the number of rows
+  // modified by the statement.
   //
   // Only the first ResultSet in the response contains a valid
   // [ResultSetMetadata][google.spanner.v1.ResultSetMetadata].