Making put/delete_multi in datastore.

docs/_components/datastore-getting-started.rst

@@ -43,7 +43,7 @@ Open a Python console and...
   >>> entity = datastore.Entity(key=datastore.Key('Person'))
   >>> entity['name'] = 'Your name'
   >>> entity['age'] = 25
-  >>> datastore.put([entity])
+  >>> datastore.put(entity)
   >>> list(Query(kind='Person').fetch())
   [<Entity{...} {'name': 'Your name', 'age': 25}>]
 

docs/_components/datastore-quickstart.rst

@@ -58,7 +58,7 @@ you can create entities and save them::
   >>> entity = datastore.Entity(key=datastore.Key('Person'))
   >>> entity['name'] = 'Your name'
   >>> entity['age'] = 25
-  >>> datastore.put([entity])
+  >>> datastore.put(entity)
   >>> list(datastore.Query(kind='Person').fetch())
   [<Entity{...} {'name': 'Your name', 'age': 25}>]
 

docs/index.rst

@@ -39,7 +39,7 @@ Cloud Datastore
   entity = datastore.Entity(key=datastore.Key('Person'))
   entity['name'] = 'Your name'
   entity['age'] = 25
-  datastore.put([entity])
+  datastore.put(entity)
 
 Cloud Storage
 ~~~~~~~~~~~~~

gcloud/datastore/__init__.py

@@ -55,9 +55,11 @@
 from gcloud.datastore._implicit_environ import set_default_dataset_id
 from gcloud.datastore.api import allocate_ids
 from gcloud.datastore.api import delete
+from gcloud.datastore.api import delete_multi
 from gcloud.datastore.api import get
 from gcloud.datastore.api import get_multi
 from gcloud.datastore.api import put
+from gcloud.datastore.api import put_multi
 from gcloud.datastore.batch import Batch
 from gcloud.datastore.connection import SCOPE
 from gcloud.datastore.connection import Connection

gcloud/datastore/api.py

@@ -274,7 +274,7 @@ def get(key, missing=None, deferred=None, connection=None, dataset_id=None):
         return entities[0]
 
 
-def put(entities, connection=None, dataset_id=None):
+def put_multi(entities, connection=None, dataset_id=None):
     """Save the entities in the Cloud Datastore.
 
     :type entities: list of :class:`gcloud.datastore.entity.Entity`
@@ -312,7 +312,30 @@ def put(entities, connection=None, dataset_id=None):
         current.commit()
 
 
-def delete(keys, connection=None, dataset_id=None):
+def put(entity, connection=None, dataset_id=None):
+    """Save the entity in the Cloud Datastore.
+
+    .. note::
+
+       This is just a thin wrapper over :func:`gcloud.datastore.put_multi`.
+       The backend API does not make a distinction between a single entity or
+       multiple entities in a commit request.
+
+    :type entity: :class:`gcloud.datastore.entity.Entity`
+    :param entity: The entity to be saved to the datastore.
+
+    :type connection: :class:`gcloud.datastore.connection.Connection`
+    :param connection: Optional connection used to connect to datastore.
+                       If not passed, inferred from the environment.
+
+    :type dataset_id: :class:`gcloud.datastore.connection.Connection`
+    :param dataset_id: Optional. The dataset ID used to connect to datastore.
+                       If not passed, inferred from the environment.
+    """
+    put_multi([entity], connection=connection, dataset_id=dataset_id)
+
+
+def delete_multi(keys, connection=None, dataset_id=None):
     """Delete the keys in the Cloud Datastore.
 
     :type keys: list of :class:`gcloud.datastore.key.Key`
@@ -348,6 +371,29 @@ def delete(keys, connection=None, dataset_id=None):
         current.commit()
 
 
+def delete(key, connection=None, dataset_id=None):
+    """Delete the key in the Cloud Datastore.
+
+    .. note::
+
+       This is just a thin wrapper over :func:`gcloud.datastore.delete_multi`.
+       The backend API does not make a distinction between a single key or
+       multiple keys in a commit request.
+
+    :type key: :class:`gcloud.datastore.key.Key`
+    :param key: The key to be deleted from the datastore.
+
+    :type connection: :class:`gcloud.datastore.connection.Connection`
+    :param connection: Optional connection used to connect to datastore.
+                       If not passed, inferred from the environment.
+
+    :type dataset_id: :class:`gcloud.datastore.connection.Connection`
+    :param dataset_id: Optional. The dataset ID used to connect to datastore.
+                       If not passed, inferred from the environment.
+    """
+    delete_multi([key], connection=connection, dataset_id=dataset_id)
+
+
 def allocate_ids(incomplete_key, num_ids, connection=None):
     """Allocates a list of IDs from a partial key.
 

gcloud/datastore/dataset.py

@@ -14,9 +14,11 @@
 """Convenience wrapper for invoking APIs/factories w/ a dataset ID."""
 
 from gcloud.datastore.api import delete
+from gcloud.datastore.api import delete_multi
 from gcloud.datastore.api import get
 from gcloud.datastore.api import get_multi
 from gcloud.datastore.api import put
+from gcloud.datastore.api import put_multi
 from gcloud.datastore.batch import Batch
 from gcloud.datastore.key import Key
 from gcloud.datastore.query import Query
@@ -56,22 +58,38 @@ def get_multi(self, keys, missing=None, deferred=None):
                          connection=self.connection,
                          dataset_id=self.dataset_id)
 
-    def put(self, entities):
+    def put(self, entity):
         """Proxy to :func:`gcloud.datastore.api.put`.
 
         Passes our ``dataset_id``.
         """
-        return put(entities, connection=self.connection,
+        return put(entity, connection=self.connection,
                    dataset_id=self.dataset_id)
 
-    def delete(self, keys):
+    def put_multi(self, entities):
+        """Proxy to :func:`gcloud.datastore.api.put_multi`.
+
+        Passes our ``dataset_id``.
+        """
+        return put_multi(entities, connection=self.connection,
+                         dataset_id=self.dataset_id)
+
+    def delete(self, key):
         """Proxy to :func:`gcloud.datastore.api.delete`.
 
         Passes our ``dataset_id``.
         """
-        return delete(keys, connection=self.connection,
+        return delete(key, connection=self.connection,
                       dataset_id=self.dataset_id)
 
+    def delete_multi(self, keys):
+        """Proxy to :func:`gcloud.datastore.api.delete_multi`.
+
+        Passes our ``dataset_id``.
+        """
+        return delete_multi(keys, connection=self.connection,
+                            dataset_id=self.dataset_id)
+
     def key(self, *path_args, **kwargs):
         """Proxy to :class:`gcloud.datastore.key.Key`.
 

gcloud/datastore/demo/demo.py

@@ -30,13 +30,13 @@
 toy.update({'name': 'Toy'})
 
 # Now let's save it to our datastore:
-datastore.put([toy])
+datastore.put(toy)
 
 # If we look it up by its key, we should find it...
 print(datastore.get(toy.key))
 
 # And we should be able to delete it...
-datastore.delete([toy.key])
+datastore.delete(toy.key)
 
 # Since we deleted it, if we do another lookup it shouldn't be there again:
 print(datastore.get(toy.key))
@@ -57,7 +57,7 @@
     entity = datastore.Entity(key)
     entity['name'] = name
     entity['age'] = age
-    datastore.put([entity])
+    datastore.put(entity)
 # We'll start by look at all Thing entities:
 query = datastore.Query(kind='Thing')
 
@@ -74,7 +74,7 @@
 print(list(query.fetch()))
 
 # Now delete them.
-datastore.delete(sample_keys)
+datastore.delete_multi(sample_keys)
 
 # You can also work inside a transaction.
 # (Check the official docs for explanations of what's happening here.)
@@ -94,7 +94,7 @@
     print('Committing the transaction...')
 
 # Now that the transaction is commited, let's delete the entities.
-datastore.delete([key, key2])
+datastore.delete_multi([key, key2])
 
 # To rollback a transaction, just call .rollback()
 with datastore.Transaction() as xact:
@@ -118,4 +118,4 @@
 print(thing.key)  # This will be complete
 
 # Now let's delete the entity.
-datastore.delete([thing.key])
+datastore.delete(thing.key)

gcloud/datastore/entity.py

@@ -65,7 +65,8 @@ class Entity(dict):
 
     :type key: :class:`gcloud.datastore.key.Key`
     :param key: Optional key to be set on entity. Required for
-                :func:`gcloud.datastore.put()`
+                :func:`gcloud.datastore.put()` and
+                :func:`gcloud.datastore.put_multi()`
 
     :type exclude_from_indexes: tuple of string
     :param exclude_from_indexes: Names of fields whose values are not to be

gcloud/datastore/test_api.py

@@ -617,7 +617,7 @@ def test_miss(self):
         self.assertTrue(result is None)
 
 
-class Test_put_function(unittest2.TestCase):
+class Test_put_multi_function(unittest2.TestCase):
 
     def setUp(self):
         from gcloud.datastore._testing import _setup_defaults
@@ -628,8 +628,9 @@ def tearDown(self):
         _tear_down_defaults(self)
 
     def _callFUT(self, entities, connection=None, dataset_id=None):
-        from gcloud.datastore.api import put
-        return put(entities, connection=connection, dataset_id=dataset_id)
+        from gcloud.datastore.api import put_multi
+        return put_multi(entities, connection=connection,
+                         dataset_id=dataset_id)
 
     def test_no_connection(self):
         from gcloud.datastore import _implicit_environ
@@ -762,7 +763,50 @@ def test_implicit_connection(self):
         self.assertEqual(len(CURR_BATCH.mutation.delete), 0)
 
 
-class Test_delete_function(unittest2.TestCase):
+class Test_put_function(unittest2.TestCase):
+
+    def setUp(self):
+        from gcloud.datastore._testing import _setup_defaults
+        _setup_defaults(self)
+
+    def tearDown(self):
+        from gcloud.datastore._testing import _tear_down_defaults
+        _tear_down_defaults(self)
+
+    def _callFUT(self, entity, connection=None, dataset_id=None):
+        from gcloud.datastore.api import put
+        return put(entity, connection=connection, dataset_id=dataset_id)
+
+    def test_implicit_connection(self):
+        from gcloud.datastore._testing import _monkey_defaults
+        from gcloud.datastore.test_batch import _Connection
+        from gcloud.datastore.test_batch import _Entity
+        from gcloud.datastore.test_batch import _Key
+
+        # Build basic mocks needed to delete.
+        _DATASET = 'DATASET'
+        connection = _Connection()
+        entity = _Entity(foo=u'bar')
+        key = entity.key = _Key(_DATASET)
+
+        with _monkey_defaults(connection=connection):
+            # Set up Batch on stack so we can check it is used.
+            with _NoCommitBatch(_DATASET, connection) as CURR_BATCH:
+                result = self._callFUT(entity)
+
+        self.assertEqual(result, None)
+        self.assertEqual(len(CURR_BATCH.mutation.insert_auto_id), 0)
+        self.assertEqual(len(CURR_BATCH.mutation.upsert), 1)
+        upserts = list(CURR_BATCH.mutation.upsert)
+        self.assertEqual(len(upserts), 1)
+        self.assertEqual(upserts[0].key, key.to_protobuf())
+        properties = list(upserts[0].property)
+        self.assertEqual(properties[0].name, 'foo')
+        self.assertEqual(properties[0].value.string_value, u'bar')
+        self.assertEqual(len(CURR_BATCH.mutation.delete), 0)
+
+
+class Test_delete_multi_function(unittest2.TestCase):
 
     def setUp(self):
         from gcloud.datastore._testing import _setup_defaults
@@ -773,8 +817,8 @@ def tearDown(self):
         _tear_down_defaults(self)
 
     def _callFUT(self, keys, connection=None, dataset_id=None):
-        from gcloud.datastore.api import delete
-        return delete(keys, connection=connection, dataset_id=dataset_id)
+        from gcloud.datastore.api import delete_multi
+        return delete_multi(keys, connection=connection, dataset_id=dataset_id)
 
     def test_no_connection(self):
         from gcloud.datastore import _implicit_environ
@@ -918,6 +962,38 @@ def test_implicit_connection_and_dataset_id(self):
         self.assertEqual(len(connection._committed), 0)
 
 
+class Test_delete_function(unittest2.TestCase):
+
+    def setUp(self):
+        from gcloud.datastore._testing import _setup_defaults
+        _setup_defaults(self)
+
+    def tearDown(self):
+        from gcloud.datastore._testing import _tear_down_defaults
+        _tear_down_defaults(self)
+
+    def _callFUT(self, key, connection=None, dataset_id=None):
+        from gcloud.datastore.api import delete
+        return delete(key, connection=connection, dataset_id=dataset_id)
+
+    def test_no_batch(self):
+        from gcloud.datastore.test_batch import _Connection
+        from gcloud.datastore.test_batch import _Key
+
+        # Build basic mocks needed to delete.
+        _DATASET = 'DATASET'
+        connection = _Connection()
+        key = _Key(_DATASET)
+
+        result = self._callFUT(key, connection=connection,
+                               dataset_id=_DATASET)
+        self.assertEqual(result, None)
+        self.assertEqual(len(connection._committed), 1)
+        dataset_id, mutation = connection._committed[0]
+        self.assertEqual(dataset_id, _DATASET)
+        self.assertEqual(list(mutation.delete), [key.to_protobuf()])
+
+
 class Test_allocate_ids_function(unittest2.TestCase):
 
     def _callFUT(self, incomplete_key, num_ids, connection=None):