#514: add datastore.put API, remove `Entity.save'

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/api.py

@@ -70,6 +70,9 @@ def _get_dataset_id_from_keys(keys):
  :returns: The dataset ID of the keys.
  :raises: :class:`ValueError` if the key dataset IDs don't agree.
  """
+ if any(key is None for key in keys):
+ raise ValueError('None not allowed')
+
  dataset_id = keys[0].dataset_id
  # Rather than creating a list or set of all dataset IDs, we iterate
  # and check. We could allow the backend to check this for us if IDs
@@ -133,6 +136,32 @@ def get(keys, missing=None, deferred=None, connection=None):
  return entities
 
 
+def put(entities, connection=None):
+ """Save the entities in the Cloud Datastore.
+
+ :type entities: list of :class:`gcloud.datastore.entity.Entity`
+ :param entities: The entities to be saved to the datastore.
+
+ :type connection: :class:`gcloud.datastore.connection.Connection`
+ :param connection: Optional connection used to connect to datastore.
+ """
+ if not entities:
+ return
+
+ connection = connection or _implicit_environ.CONNECTION
+
+ current = _BATCHES.top
+ in_batch = current is not None
+ if not in_batch:
+ keys = [entity.key for entity in entities]
+ dataset_id = _get_dataset_id_from_keys(keys)
+ current = Batch(dataset_id=dataset_id, connection=connection)
+ for entity in entities:
+ current.put(entity)
+ if not in_batch:
+ current.commit()
+
+
 def delete(keys, connection=None):
  """Delete the keys in the Cloud Datastore.
 

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,12 +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."""
-
 
 class Entity(dict):
  """Entities are akin to rows in a relational database
@@ -70,8 +64,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
+:func:`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 +98,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,