Remove 'Entity.save'.

Author: tseaver

docs/_components/datastore-getting-started.rst

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

docs/index.rst

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

gcloud/datastore/__init__.py

@@ -53,6 +53,7 @@
 from gcloud.datastore.api import allocate_ids
 from gcloud.datastore.api import delete
 from gcloud.datastore.api import get
+from gcloud.datastore.api import put
 from gcloud.datastore.batch import Batch
 from gcloud.datastore.connection import Connection
 from gcloud.datastore.entity import Entity

gcloud/datastore/demo/demo.py

@@ -28,7 +28,7 @@
 toy.update({'name': 'Toy'})
 
 # Now let's save it to our datastore:
-toy.save()
+datastore.put([toy])
 
 # If we look it up by its key, we should find it...
 print(datastore.get([toy.key]))
@@ -55,7 +55,7 @@
     entity = datastore.Entity(key)
     entity['name'] = name
     entity['age'] = age
-    entity.save()
+    datastore.put([entity])
 # We'll start by look at all Thing entities:
 query = datastore.Query(kind='Thing')
 
@@ -76,41 +76,41 @@
 
 # You can also work inside a transaction.
 # (Check the official docs for explanations of what's happening here.)
-with datastore.Transaction():
+with datastore.Transaction() as xact:
     print('Creating and saving an entity...')
     key = datastore.Key('Thing', 'foo')
     thing = datastore.Entity(key)
     thing['age'] = 10
-    thing.save()
+    xact.put(thing)
 
     print('Creating and saving another entity...')
     key2 = datastore.Key('Thing', 'bar')
     thing2 = datastore.Entity(key2)
     thing2['age'] = 15
-    thing2.save()
+    xact.put(thing2)
 
     print('Committing the transaction...')
 
 # Now that the transaction is commited, let's delete the entities.
 datastore.delete([key, key2])
 
 # To rollback a transaction, just call .rollback()
-with datastore.Transaction() as t:
+with datastore.Transaction() as xact:
     key = datastore.Key('Thing', 'another')
     thing = datastore.Entity(key)
-    thing.save()
-    t.rollback()
+    xact.put(thing)
+    xact.rollback()
 
 # Let's check if the entity was actually created:
 created = datastore.get([key])
 print('yes' if created else 'no')
 
 # Remember, a key won't be complete until the transaction is commited.
 # That is, while inside the transaction block, thing.key will be incomplete.
-with datastore.Transaction():
+with datastore.Transaction() as xact:
     key = datastore.Key('Thing')  # partial
     thing = datastore.Entity(key)
-    thing.save()
+    xact.put(thing)
     print(thing.key)  # This will still be partial
 
 print(thing.key)  # This will be complete

gcloud/datastore/entity.py

@@ -14,8 +14,6 @@
 
 """Class for representing a single entity in the Cloud Datastore."""
 
-from gcloud.datastore import _implicit_environ
-
 
 class NoKey(RuntimeError):
     """Exception raised by Entity methods which require a key."""
@@ -70,8 +68,8 @@ class Entity(dict):
        any decoding / encoding step.
 
     :type key: :class:`gcloud.datastore.key.Key`
-    :param key: Optional key to be set on entity. Required for :meth:`save()`
-                or :meth:`reload()`.
+    :param key: Optional key to be set on entity. Required for
+                :fund:`gcloud.datastore.put()`
 
     :type exclude_from_indexes: tuple of string
     :param exclude_from_indexes: Names of fields whose values are not to be
@@ -104,55 +102,6 @@ def exclude_from_indexes(self):
         """
         return frozenset(self._exclude_from_indexes)
 
-    @property
-    def _must_key(self):
-        """Return our key, or raise NoKey if not set.
-
-        :rtype: :class:`gcloud.datastore.key.Key`.
-        :returns: The entity's key.
-        :raises: :class:`NoKey` if no key is set.
-        """
-        if self.key is None:
-            raise NoKey()
-        return self.key
-
-    def save(self, connection=None):
-        """Save the entity in the Cloud Datastore.
-
-        .. note::
-           Any existing properties for the entity will be replaced by those
-           currently set on this instance.  Already-stored properties which do
-           not correspond to keys set on this instance will be removed from
-           the datastore.
-
-        .. note::
-           Property values which are "text" (``unicode`` in Python2, ``str`` in
-           Python3) map to 'string_value' in the datastore;  values which are
-           "bytes" (``str`` in Python2, ``bytes`` in Python3) map to
-           'blob_value'.
-
-        :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
-        assigned, new_id = connection.save_entity(
-            dataset_id=key.dataset_id,
-            key_pb=key.to_protobuf(),
-            properties=dict(self),
-            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.
-        transaction = connection.transaction()
-        if transaction and key.is_partial:
-            transaction.add_auto_id_entity(self)
-
-        if assigned:
-            # Update the key (which may have been altered).
-            self.key = self.key.completed_key(new_id)
-
     def __repr__(self):
         if self.key:
             return '<Entity%s %s>' % (self.key.path,

gcloud/datastore/test_entity.py

@@ -53,79 +53,6 @@ def test_ctor_explicit(self):
         self.assertEqual(sorted(entity.exclude_from_indexes),
                          sorted(_EXCLUDE_FROM_INDEXES))
 
-    def test__must_key_no_key(self):
-        from gcloud.datastore.entity import NoKey
-
-        entity = self._makeOne()
-        self.assertRaises(NoKey, getattr, entity, '_must_key')
-
-    def test_save_no_key(self):
-        from gcloud.datastore.entity import NoKey
-
-        entity = self._makeOne()
-        entity['foo'] = 'Foo'
-        self.assertRaises(NoKey, entity.save)
-
-    def test_save_wo_transaction_wo_auto_id_wo_returned_key(self):
-        connection = _Connection()
-        key = _Key()
-        entity = self._makeOne(key=key)
-        entity['foo'] = 'Foo'
-        entity.save(connection=connection)
-        self.assertEqual(entity['foo'], 'Foo')
-        self.assertEqual(connection._saved,
-                         (_DATASET_ID, 'KEY', {'foo': 'Foo'}, ()))
-        self.assertEqual(key._path, None)
-
-    def test_save_w_transaction_wo_partial_key(self):
-        connection = _Connection()
-        transaction = connection._transaction = _Transaction()
-        key = _Key()
-        entity = self._makeOne(key=key)
-        entity['foo'] = 'Foo'
-        entity.save(connection=connection)
-        self.assertEqual(entity['foo'], 'Foo')
-        self.assertEqual(connection._saved,
-                         (_DATASET_ID, 'KEY', {'foo': 'Foo'}, ()))
-        self.assertEqual(transaction._added, ())
-        self.assertEqual(key._path, None)
-
-    def test_save_w_transaction_w_partial_key(self):
-        connection = _Connection()
-        transaction = connection._transaction = _Transaction()
-        key = _Key()
-        key._partial = True
-        entity = self._makeOne(key=key)
-        entity['foo'] = 'Foo'
-        entity.save(connection=connection)
-        self.assertEqual(entity['foo'], 'Foo')
-        self.assertEqual(connection._saved,
-                         (_DATASET_ID, 'KEY', {'foo': 'Foo'}, ()))
-        self.assertEqual(transaction._added, (entity,))
-        self.assertEqual(key._path, None)
-
-    def test_save_w_returned_key_exclude_from_indexes(self):
-        from gcloud.datastore import datastore_v1_pb2 as datastore_pb
-        from gcloud.datastore.key import Key
-
-        key_pb = datastore_pb.Key()
-        key_pb.partition_id.dataset_id = _DATASET_ID
-        key_pb.path_element.add(kind=_KIND, id=_ID)
-        connection = _Connection()
-        connection._save_result = (True, _ID)
-        key = Key('KIND', dataset_id=_DATASET_ID)
-        entity = self._makeOne(key=key, exclude_from_indexes=['foo'])
-        entity['foo'] = 'Foo'
-        entity.save(connection=connection)
-        self.assertEqual(entity['foo'], 'Foo')
-        self.assertEqual(connection._saved[0], _DATASET_ID)
-        self.assertEqual(connection._saved[1], key.to_protobuf())
-        self.assertEqual(connection._saved[2], {'foo': 'Foo'})
-        self.assertEqual(connection._saved[3], ('foo',))
-        self.assertEqual(len(connection._saved), 4)
-
-        self.assertEqual(entity.key._path, [{'kind': _KIND, 'id': _ID}])
-
     def test___repr___no_key_empty(self):
         entity = self._makeOne()
         self.assertEqual(repr(entity), '<Entity {}>')
@@ -149,38 +76,6 @@ class _Key(object):
     def __init__(self, dataset_id=_DATASET_ID):
         self.dataset_id = dataset_id
 
-    def to_protobuf(self):
-        return self._key
-
-    @property
-    def is_partial(self):
-        return self._partial
-
     @property
     def path(self):
         return self._path
-
-
-class _Connection(object):
-    _transaction = _saved = _deleted = None
-    _save_result = (False, None)
-
-    def transaction(self):
-        return self._transaction
-
-    def save_entity(self, dataset_id, key_pb, properties,
-                    exclude_from_indexes=()):
-        self._saved = (dataset_id, key_pb, properties,
-                       tuple(exclude_from_indexes))
-        return self._save_result
-
-
-class _Transaction(object):
-    _added = ()
-
-    def __nonzero__(self):
-        return True
-    __bool__ = __nonzero__
-
-    def add_auto_id_entity(self, entity):
-        self._added += (entity,)

gcloud/datastore/transaction.py

@@ -32,16 +32,16 @@ class Transaction(Batch):
 
       >>> datastore.set_defaults()
 
-      >>> with Transaction()
-      ...     entity1.save()
-      ...     entity2.save()
+      >>> with Transaction() as xact:
+      ...     datastore.put(entity1)
+      ...     datastore.put(entity2)
 
     Because it derives from :class:`Batch`, :class`Transaction` also provides
     :meth:`put` and :meth:`delete` methods::
 
-      >>> with Transaction()
-      ...     transaction.put(entity1)
-      ...     transaction.delete(entity2.key)
+      >>> with Transaction() as xact:
+      ...     xact.put(entity1)
+      ...     xact.delete(entity2.key)
 
     By default, the transaction is rolled back if the transaction block
     exits with an error::
@@ -59,7 +59,7 @@ class Transaction(Batch):
 
          >>> with Transaction():
          ...     entity = Entity(key=Key('Thing'))
-         ...     entity.save()
+         ...     datastore.put([entity])
 
        ``entity`` won't have a complete Key until the transaction is
        committed.
@@ -69,7 +69,7 @@ class Transaction(Batch):
 
          >>> with Transaction():
          ...     entity = Entity(key=Key('Thing'))
-         ...     entity.save()
+         ...     datastore.put([entity])
          ...     assert entity.key.is_partial  # There is no ID on this key.
          >>> assert not entity.key.is_partial  # There *is* an ID.
 
@@ -89,34 +89,13 @@ class Transaction(Batch):
       >>> transaction.begin()
 
       >>> entity = Entity(key=Key('Thing'))
-      >>> entity.save()
+      >>> datastore.put([entity])
 
       >>> if error:
       ...     transaction.rollback()
       ... else:
       ...     transaction.commit()
 
-    For now, this library will enforce a rule of one transaction per
-    connection.  That is, If you want to work with two transactions at
-    the same time (for whatever reason), that must happen over two
-    separate :class:`gcloud.datastore.connection.Connection` s.
-
-    For example, this is perfectly valid::
-
-      >>> with Transaction():
-      ...     entity = Entity(key=Key('Thing'))
-      ...     entity.save()
-
-    However, this **wouldn't** be acceptable::
-
-      >>> with Transaction():
-      ...     Entity(key=Key('Thing')).save()
-      ...     with Transaction():
-      ...         Entity(key=Key('Thing')).save()
-
-    Technically, it looks like the Protobuf API supports this type of
-    pattern, however it makes the code particularly messy.
-
     :type dataset_id: string
     :param dataset_id: The ID of the dataset.