Implementing Cluster.reload().

Also
- Implementing Cluster.name property which is used
  to identify the cluster in API requests
- Moving _FakeStub and _MethodMock to a shared testing
  module for Bigtable.
- Adding Client to root bigtable package.
- Fixing typo in Bigtable Client docstring

Author: dhermes

gcloud/bigtable/__init__.py

@@ -27,3 +27,5 @@
               'to set your LD_LIBRARY_PATH variable to help '
               'Python locate the libraries.', file=sys.stderr)
     raise
+
+from gcloud.bigtable.client import Client

gcloud/bigtable/_testing.py

@@ -0,0 +1,57 @@
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Mocks used to emulate gRPC generated objects."""
+
+
+class _FakeStub(object):
+    """Acts as a gPRC stub."""
+
+    def __init__(self, *results):
+        self.results = results
+        self.method_calls = []
+        self._entered = 0
+        self._exited = []
+
+    def __enter__(self):
+        self._entered += 1
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self._exited.append((exc_type, exc_val, exc_tb))
+        return True
+
+    def __getattr__(self, name):
+        # We need not worry about attributes set in constructor
+        # since __getattribute__ will handle them.
+        return _MethodMock(name, self)
+
+
+class _MethodMock(object):
+    """Mock for API method attached to a gRPC stub.
+
+    In the beta implementation, these are of type.
+    :class:`grpc.framework.crust.implementations._UnaryUnaryMultiCallable`
+    """
+
+    def __init__(self, name, factory):
+        self._name = name
+        self._factory = factory
+
+    def __call__(self, *args, **kwargs):
+        """Sync method meant to mock a gRPC stub request."""
+        self._factory.method_calls.append((self._name, args, kwargs))
+        curr_result, self._factory.results = (self._factory.results[0],
+                                              self._factory.results[1:])
+        return curr_result

gcloud/bigtable/client.py

@@ -97,7 +97,7 @@ class Client(_ClientFactoryMixin, _ClientProjectMixin):
         :class:`OAuth2Credentials <oauth2client.client.OAuth2Credentials>` or
         :data:`NoneType <types.NoneType>`
     :param credentials: (Optional) The OAuth2 Credentials to use for this
-                        cluster. If not provided, defaulst to the Google
+                        cluster. If not provided, defaults to the Google
                         Application Default Credentials.
 
     :type read_only: bool

gcloud/bigtable/cluster.py

@@ -17,6 +17,8 @@
 
 import re
 
+from gcloud.bigtable._generated import (
+    bigtable_cluster_service_messages_pb2 as messages_pb2)
 from gcloud.bigtable.table import Table
 
 
@@ -124,6 +126,24 @@ def from_pb(cls, cluster_pb, client):
         result._update_from_pb(cluster_pb)
         return result
 
+    @property
+    def name(self):
+        """Cluster name used in requests.
+
+        .. note::
+          This property will not change if ``zone`` and ``cluster_id`` do not,
+          but the return value is not cached.
+
+        The cluster name is of the form
+
+            ``"projects/{project}/zones/{zone}/clusters/{cluster_id}"``
+
+        :rtype: str
+        :returns: The cluster name.
+        """
+        return (self._client.project_name + '/zones/' + self.zone +
+                '/clusters/' + self.cluster_id)
+
     def __eq__(self, other):
         if not isinstance(other, self.__class__):
             return False
@@ -139,3 +159,14 @@ def __eq__(self, other):
 
     def __ne__(self, other):
         return not self.__eq__(other)
+
+    def reload(self):
+        """Reload the metadata for this cluster."""
+        request_pb = messages_pb2.GetClusterRequest(name=self.name)
+        # We expect a `._generated.bigtable_cluster_data_pb2.Cluster`.
+        cluster_pb = self._client._cluster_stub.GetCluster(
+            request_pb, self._client.timeout_seconds)
+
+        # NOTE: _update_from_pb does not check that the project, zone and
+        #       cluster ID on the response match the request.
+        self._update_from_pb(cluster_pb)

gcloud/bigtable/test_client.py

@@ -379,6 +379,7 @@ def test_is_started(self):
 
     def _start_method_helper(self, admin):
         from gcloud._testing import _Monkey
+        from gcloud.bigtable._testing import _FakeStub
         from gcloud.bigtable import client as MUT
 
         credentials = _Credentials()
@@ -429,6 +430,8 @@ def test_start_while_started(self):
         self.assertEqual(client._data_stub_internal, data_stub)
 
     def _stop_method_helper(self, admin):
+        from gcloud.bigtable._testing import _FakeStub
+
         credentials = _Credentials()
         project = 'PROJECT'
         client = self._makeOne(project=project, credentials=credentials,
@@ -499,6 +502,7 @@ def _list_zones_helper(self, zone_status):
             bigtable_cluster_data_pb2 as data_pb2)
         from gcloud.bigtable._generated import (
             bigtable_cluster_service_messages_pb2 as messages_pb2)
+        from gcloud.bigtable._testing import _FakeStub
 
         credentials = _Credentials()
         project = 'PROJECT'
@@ -552,6 +556,7 @@ def test_list_clusters(self):
             bigtable_cluster_data_pb2 as data_pb2)
         from gcloud.bigtable._generated import (
             bigtable_cluster_service_messages_pb2 as messages_pb2)
+        from gcloud.bigtable._testing import _FakeStub
 
         credentials = _Credentials()
         project = 'PROJECT'
@@ -625,45 +630,3 @@ def create_scoped(self, scope):
 
     def __eq__(self, other):
         return self.value == other.value
-
-
-class _FakeStub(object):
-    """Acts as a gPRC stub."""
-
-    def __init__(self, *results):
-        self.results = results
-        self.method_calls = []
-        self._entered = 0
-        self._exited = []
-
-    def __enter__(self):
-        self._entered += 1
-        return self
-
-    def __exit__(self, exc_type, exc_val, exc_tb):
-        self._exited.append((exc_type, exc_val, exc_tb))
-        return True
-
-    def __getattr__(self, name):
-        # We need not worry about attributes set in constructor
-        # since __getattribute__ will handle them.
-        return _MethodMock(name, self)
-
-
-class _MethodMock(object):
-    """Mock for API method attached to a gRPC stub.
-
-    In the beta implementation, these are of type.
-    :class:`grpc.framework.crust.implementations._UnaryUnaryMultiCallable`
-    """
-
-    def __init__(self, name, factory):
-        self._name = name
-        self._factory = factory
-
-    def __call__(self, *args, **kwargs):
-        """Sync method meant to mock a gRPC stub request."""
-        self._factory.method_calls.append((self._name, args, kwargs))
-        curr_result, self._factory.results = (self._factory.results[0],
-                                              self._factory.results[1:])
-        return curr_result

gcloud/bigtable/test_cluster.py

@@ -121,6 +121,17 @@ def test_from_pb_project_mistmatch(self):
         with self.assertRaises(ValueError):
             klass.from_pb(cluster_pb, client)
 
+    def test_name_property(self):
+        project = 'PROJECT'
+        zone = 'zone'
+        cluster_id = 'cluster-id'
+        client = _Client(project=project)
+
+        cluster = self._makeOne(zone, cluster_id, client)
+        cluster_name = ('projects/' + project + '/zones/' + zone +
+                        '/clusters/' + cluster_id)
+        self.assertEqual(cluster.name, cluster_name)
+
     def test___eq__(self):
         zone = 'zone'
         cluster_id = 'cluster_id'
@@ -148,6 +159,46 @@ def test___ne__(self):
         cluster2 = self._makeOne('zone2', 'cluster_id2', 'client2')
         self.assertNotEqual(cluster1, cluster2)
 
+    def test_reload(self):
+        from gcloud.bigtable._generated import (
+            bigtable_cluster_data_pb2 as data_pb2)
+        from gcloud.bigtable._generated import (
+            bigtable_cluster_service_messages_pb2 as messages_pb2)
+        from gcloud.bigtable._testing import _FakeStub
+
+        project = 'PROJECT'
+        zone = 'zone'
+        cluster_id = 'cluster-id'
+        timeout_seconds = 123
+        client = _Client(project=project, timeout_seconds=timeout_seconds)
+        cluster = self._makeOne(zone, cluster_id, client)
+
+        # Create request_pb
+        cluster_name = ('projects/' + project + '/zones/' + zone +
+                        '/clusters/' + cluster_id)
+        request_pb = messages_pb2.GetClusterRequest(name=cluster_name)
+
+        # Create response_pb
+        response_pb = data_pb2.Cluster(
+            display_name=cluster_id,
+            serve_nodes=3,
+        )
+
+        # Patch the stub used by the API method.
+        client._cluster_stub = stub = _FakeStub(response_pb)
+
+        # Create expected_result.
+        expected_result = None  # reload() has no return value.
+
+        # Perform the method and check the result.
+        result = cluster.reload()
+        self.assertEqual(result, expected_result)
+        self.assertEqual(stub.method_calls, [(
+            'GetCluster',
+            (request_pb, timeout_seconds),
+            {},
+        )])
+
 
 class Test__get_pb_property_value(unittest2.TestCase):
 
@@ -173,5 +224,7 @@ def test_with_value_unset_on_pb(self):
 
 class _Client(object):
 
-    def __init__(self, project):
+    def __init__(self, project, timeout_seconds=None):
         self.project = project
+        self.project_name = 'projects/' + self.project
+        self.timeout_seconds = timeout_seconds