Changing constructor of Entity to take a Key.

Also:
- Dropping dataset and kind from Entity constructor.
- Dropping Entity.from_path factory.
- Removing Connection.dataset().
- helpers.entity_from_protobuf() no longer requires dataset.
- Making Entity.key a data attribute instead of a getter/setter method.
- Removing Entity.dataset() (since no longer stored).
- Making Entity.kind() and Entity.exclude_from_indexes() @Property's.
- Removing Entity._must_dataset (no longer needed).
- Adding optional connection argument to Entity.save() and Entity.reload().
- Making Entity.save() and Entity.reload() return nothing.
- Updating regression/datastore.py for changes.

Author: dhermes

gcloud/datastore/__init__.py

@@ -49,6 +49,7 @@
 from gcloud import credentials
 from gcloud.datastore import _implicit_environ
 from gcloud.datastore import connection as connection_module
+from gcloud.datastore.dataset import Dataset
 
 
 SCOPE = ('https://www.googleapis.com/auth/datastore ',
@@ -131,7 +132,7 @@ def get_dataset(dataset_id):
     :returns: A dataset with a connection using the provided credentials.
     """
     connection = get_connection()
-    return connection.dataset(dataset_id)
+    return Dataset(dataset_id, connection=connection)
 
 
 def _require_dataset():

gcloud/datastore/connection.py

@@ -17,7 +17,6 @@
 from gcloud import connection as base_connection
 from gcloud.datastore import datastore_v1_pb2 as datastore_pb
 from gcloud.datastore import helpers
-from gcloud.datastore.dataset import Dataset
 
 
 class Connection(base_connection.Connection):
@@ -154,19 +153,6 @@ def mutation(self):
         else:
             return datastore_pb.Mutation()
 
-    def dataset(self, *args, **kwargs):
-        """Factory method for Dataset objects.
-
-        :param args: All args and kwargs will be passed along to the
-                     :class:`gcloud.datastore.dataset.Dataset` initializer.
-
-        :rtype: :class:`gcloud.datastore.dataset.Dataset`
-        :returns: A dataset object that will use this connection as
-                  its transport.
-        """
-        kwargs['connection'] = self
-        return Dataset(*args, **kwargs)
-
     def lookup(self, dataset_id, key_pbs,
                missing=None, deferred=None, eventual=False):
         """Lookup keys from a dataset in the Cloud Datastore.
@@ -608,10 +594,9 @@ def get_entities(keys, connection, dataset_id, missing=None, deferred=None):
         missing=missing, deferred=deferred,
     )
 
-    new_dataset = Dataset(dataset_id, connection=connection)
     if missing is not None:
         missing[:] = [
-            helpers.entity_from_protobuf(missed_pb, dataset=new_dataset)
+            helpers.entity_from_protobuf(missed_pb)
             for missed_pb in missing]
 
     if deferred is not None:
@@ -621,8 +606,7 @@ def get_entities(keys, connection, dataset_id, missing=None, deferred=None):
 
     entities = []
     for entity_pb in entity_pbs:
-        entities.append(helpers.entity_from_protobuf(
-            entity_pb, dataset=new_dataset))
+        entities.append(helpers.entity_from_protobuf(entity_pb))
     return entities
 
 

gcloud/datastore/entity.py

@@ -15,17 +15,12 @@
 """Class for representing a single entity in the Cloud Datastore."""
 
 from gcloud.datastore import _implicit_environ
-from gcloud.datastore.key import Key
 
 
 class NoKey(RuntimeError):
     """Exception raised by Entity methods which require a key."""
 
 
-class NoDataset(RuntimeError):
-    """Exception raised by Entity methods which require a dataset."""
-
-
 class Entity(dict):
     """Entities are akin to rows in a relational database
 
@@ -75,72 +70,21 @@ class Entity(dict):
        Python3), will be saved using the 'blob_value' field, without
        any decoding / encoding step.
 
-    :type dataset: :class:`gcloud.datastore.dataset.Dataset`
-    :param dataset: The dataset in which this entity belongs.
-
-    :type kind: string
-    :param kind: The kind of entity this is, akin to a table name in a
-                 relational database.
-
-    :type dataset: :class:`gcloud.datastore.dataset.Dataset`, or None
-    :param dataset: the Dataset instance associated with this entity.
-
-    :type kind: str
-    :param kind: the "kind" of the entity (see
-                 https://cloud.google.com/datastore/docs/concepts/entities#Datastore_Kinds_and_identifiers)
+    :type key: :class:`gcloud.datastore.key.Key`
+    :param key: Optional key to be set on entity. Required for save() or
+                reload().
 
+    :type exclude_from_indexes: `tuple` of :class:`str`
     :param exclude_from_indexes: names of fields whose values are not to be
                                  indexed for this entity.
     """
 
-    def __init__(self, dataset=None, kind=None, exclude_from_indexes=()):
+    def __init__(self, key=None, exclude_from_indexes=()):
         super(Entity, self).__init__()
-        # Does not inherit directly from object, so we don't use
-        # _implicit_environ._DatastoreBase to avoid split MRO.
-        self._dataset = dataset or _implicit_environ.DATASET
-        if kind:
-            self._key = Key(kind, dataset_id=self.dataset().id())
-        else:
-            self._key = None
+        self.key = key
         self._exclude_from_indexes = set(exclude_from_indexes)
 
-    def dataset(self):
-        """Get the :class:`.dataset.Dataset` in which this entity belongs.
-
-        .. note::
-          This is based on the :class:`gcloud.datastore.key.Key` set on the
-          entity. That means that if you have no key set, the dataset might
-          be `None`. It also means that if you change the key on the entity,
-          this will refer to that key's dataset.
-
-        :rtype: :class:`gcloud.datastore.dataset.Dataset`
-        :returns: The Dataset containing the entity if there is a key,
-                  else None.
-        """
-        return self._dataset
-
-    def key(self, key=None):
-        """Get or set the :class:`.datastore.key.Key` on the current entity.
-
-        :type key: :class:`glcouddatastore.key.Key`
-        :param key: The key you want to set on the entity.
-
-        :rtype: :class:`gcloud.datastore.key.Key` or :class:`Entity`.
-        :returns: Either the current key (on get) or the current
-                  object (on set).
-
-        >>> entity.key(my_other_key)  # This returns the original entity.
-        <Entity[{'kind': 'OtherKeyKind', 'id': 1234}] {'property': 'value'}>
-        >>> entity.key()  # This returns the key.
-        <Key[{'kind': 'OtherKeyKind', 'id': 1234}]>
-        """
-
-        if key is not None:
-            self._key = key
-            return self
-        else:
-            return self._key
-
+    @property
     def kind(self):
         """Get the kind of the current entity.
 
@@ -150,32 +94,17 @@ def kind(self):
           of the entity at all, just the properties and a pointer to a
           Key which knows its Kind.
         """
+        if self.key:
+            return self.key.kind
 
-        if self._key:
-            return self._key.kind
-
+    @property
     def exclude_from_indexes(self):
         """Names of fields which are *not* to be indexed for this entity.
 
         :rtype: sequence of field names
         """
         return frozenset(self._exclude_from_indexes)
 
-    @classmethod
-    def from_key(cls, key, dataset=None):
-        """Create entity based on :class:`.datastore.key.Key`.
-
-        .. note:: This is a factory method.
-
-        :type key: :class:`gcloud.datastore.key.Key`
-        :param key: The key for the entity.
-
-        :returns: The :class:`Entity` derived from the
-                  :class:`gcloud.datastore.key.Key`.
-        """
-
-        return cls(dataset).key(key)
-
     @property
     def _must_key(self):
         """Return our key, or raise NoKey if not set.
@@ -184,23 +113,11 @@ def _must_key(self):
         :returns: our key
         :raises: NoKey if key is None
         """
-        if self._key is None:
+        if self.key is None:
             raise NoKey()
-        return self._key
-
-    @property
-    def _must_dataset(self):
-        """Return our dataset, or raise NoDataset if not set.
-
-        :rtype: :class:`gcloud.datastore.key.Key`.
-        :returns: our key
-        :raises: NoDataset if key is None
-        """
-        if self._dataset is None:
-            raise NoDataset()
-        return self._dataset
+        return self.key
 
-    def reload(self):
+    def reload(self, connection=None):
         """Reloads the contents of this entity from the datastore.
 
         This method takes the :class:`gcloud.datastore.key.Key`, loads all
@@ -211,16 +128,19 @@ def reload(self):
           This will override any existing properties if a different value
           exists remotely, however it will *not* override any properties that
           exist only locally.
+
+        :type connection: :class:`gcloud.datastore.connection.Connection`
+        :param connection: Optional connection used to connect to datastore.
         """
+        connection = connection or _implicit_environ.CONNECTION
+
         key = self._must_key
-        connection = self._must_dataset.connection()
         entity = key.get(connection=connection)
 
         if entity:
             self.update(entity)
-        return self
 
-    def save(self):
+    def save(self, connection=None):
         """Save the entity in the Cloud Datastore.
 
         .. note::
@@ -234,17 +154,17 @@ def save(self):
            Python3) map to 'string_value' in the datastore;  values which are
            "bytes" ('str' in Python2, 'bytes' in Python3) map to 'blob_value'.
 
-        :rtype: :class:`gcloud.datastore.entity.Entity`
-        :returns: The entity with a possibly updated Key.
+        :type connection: :class:`gcloud.datastore.connection.Connection`
+        :param connection: Optional connection used to connect to datastore.
         """
+        connection = connection or _implicit_environ.CONNECTION
+
         key = self._must_key
-        dataset = self._must_dataset
-        connection = dataset.connection()
         assigned, new_id = connection.save_entity(
-            dataset_id=dataset.id(),
+            dataset_id=key.dataset_id,
             key_pb=key.to_protobuf(),
             properties=dict(self),
-            exclude_from_indexes=self.exclude_from_indexes())
+            exclude_from_indexes=self.exclude_from_indexes)
 
         # If we are in a transaction and the current entity needs an
         # automatically assigned ID, tell the transaction where to put that.
@@ -254,13 +174,11 @@ def save(self):
 
         if assigned:
             # Update the key (which may have been altered).
-            self.key(self.key().completed_key(new_id))
-
-        return self
+            self.key = self.key.completed_key(new_id)
 
     def __repr__(self):
-        if self._key:
-            return '<Entity%s %s>' % (self._key.path,
+        if self.key:
+            return '<Entity%s %s>' % (self.key.path,
                                       super(Entity, self).__repr__())
         else:
             return '<Entity %s>' % (super(Entity, self).__repr__())

gcloud/datastore/helpers.py

@@ -32,7 +32,7 @@
 INT_VALUE_CHECKER = Int64ValueChecker()
 
 
-def entity_from_protobuf(pb, dataset=None):
+def entity_from_protobuf(pb):
     """Factory method for creating an entity based on a protobuf.
 
     The protobuf should be one returned from the Cloud Datastore
@@ -45,7 +45,7 @@ def entity_from_protobuf(pb, dataset=None):
     :returns: The entity derived from the protobuf.
     """
     key = key_from_protobuf(pb.key)
-    entity = Entity.from_key(key, dataset)
+    entity = Entity(key=key)
 
     for property_pb in pb.property:
         value = _get_value_from_property_pb(property_pb)
@@ -246,7 +246,7 @@ def _set_protobuf_value(value_pb, val):
     elif attr == 'entity_value':
         e_pb = value_pb.entity_value
         e_pb.Clear()
-        key = val.key()
+        key = val.key
         if key is not None:
             e_pb.key.CopyFrom(key.to_protobuf())
         for item_key, value in val.items():

gcloud/datastore/key.py

@@ -248,7 +248,7 @@ def get(self, connection=None):
         if entities:
             result = entities[0]
             # We assume that the backend has not changed the key.
-            result.key(self)
+            result.key = self
             return result
 
     def delete(self, connection=None):

gcloud/datastore/query.py

@@ -365,8 +365,7 @@ def fetch_page(self, limit=None):
         #       for discussion.
         entity_pbs, cursor_as_bytes, more_results_enum = query_results[:3]
 
-        entities = [helpers.entity_from_protobuf(entity,
-                                                 dataset=self.dataset())
+        entities = [helpers.entity_from_protobuf(entity)
                     for entity in entity_pbs]
 
         cursor = base64.b64encode(cursor_as_bytes)

gcloud/datastore/test_connection.py

@@ -204,13 +204,6 @@ def mutation(self):
         found = conn.mutation()
         self.assertTrue(isinstance(found, Mutation))
 
-    def test_dataset(self):
-        DATASET_ID = 'DATASET'
-        conn = self._makeOne()
-        dataset = conn.dataset(DATASET_ID)
-        self.assertTrue(dataset.connection() is conn)
-        self.assertEqual(dataset.id(), DATASET_ID)
-
     def test_lookup_single_key_empty_response(self):
         from gcloud.datastore import datastore_v1_pb2 as datastore_pb
 
@@ -1178,7 +1171,7 @@ def test_get_entities_miss_w_missing(self):
         entities = self._callFUT([key], connection, DATASET_ID,
                                  missing=missing)
         self.assertEqual(entities, [])
-        self.assertEqual([missed.key().to_protobuf() for missed in missing],
+        self.assertEqual([missed.key.to_protobuf() for missed in missing],
                          [key.to_protobuf()])
 
     def test_get_entities_miss_w_deferred(self):
@@ -1222,7 +1215,7 @@ def test_get_entities_hit(self):
 
         key = Key(KIND, ID, dataset_id=DATASET_ID)
         result, = self._callFUT([key], connection, DATASET_ID)
-        new_key = result.key()
+        new_key = result.key
 
         # Check the returned value is as expected.
         self.assertFalse(new_key is key)