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'}])