feat(spanner): add deprecation warnings; add field_mask to get_instan…

…ce; add endpoint_uris to Instance proto; update timeouts; make mutations optional for commits (via synth)

docs/_static/custom.css

@@ -1,4 +1,4 @@
 div#python2-eol {
 	border-color: red;
 	border-width: medium;
-}
+} 

docs/_templates/layout.html

@@ -1,3 +1,4 @@
+
 {% extends "!layout.html" %}
 {%- block content %}
 {%- if theme_fixed_sidebar|lower == 'true' %}

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/<project>/instances/<instance>``.
-            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/<project>/instances/<instance>``.
+            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

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",
+                },
             },
         }
     }

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