Fix #135: Document / enforce gcloud.datastore.key.Key.parent() contract

gcloud/datastore/key.py

@@ -33,6 +33,9 @@ def _clone(self):
     We make a shallow copy of the :class:`gcloud.datastore.dataset.Dataset`
     because it holds a reference an authenticated connection,
     which we don't want to lose.
+
+    :rtype: :class:`gcloud.datastore.key.Key`
+    :returns: a new `Key` instance
     """
     clone = copy.deepcopy(self)
     clone._dataset = self._dataset  # Make a shallow copy of the Dataset.
@@ -259,8 +262,15 @@ def id_or_name(self):
     return self.id() or self.name()
 
   def parent(self):#pragma NO COVER
-    # See https://github.com/GoogleCloudPlatform/gcloud-python/issues/135
-    raise NotImplementedError
+    """Getter:  return a new key for the next highest element in path.
+
+    :rtype: :class:`gcloud.datastore.key.Key`
+    :returns: a new `Key` instance, whose path consists of all but the last
+    element of self's path.  If self has only one path element, return None.
+    """
+    if len(self._path) <= 1:
+        return None
+    return self.path(self.path()[:-1])
 
   def __repr__(self): #pragma NO COVER
     return '<Key%s>' % self.path()

gcloud/datastore/test_key.py

@@ -339,6 +339,14 @@ def test_id_or_name_w_name_only(self):
         key = self._makeOne(path=_PATH)
         self.assertEqual(key.id_or_name(), _NAME)
 
-    def _ugh(self):
-        protokey = key.to_protobuf()
-        self.assertEqual(protokey.partition_id.dataset_id, _DATASET)
+    def test_parent_default(self):
+        key = self._makeOne()
+        self.assertEqual(key.parent(), None)
+
+    def test_parent_explicit_top_level(self):
+        key = self._getTargetClass().from_path('abc', 'def')
+        self.assertEqual(key.parent(), None)
+
+    def test_parent_explicit_nested(self):
+        key = self._getTargetClass().from_path('abc', 'def', 'ghi', 123)
+        self.assertEqual(key.parent().path(), [{'kind': 'abc', 'name': 'def'}])