Repository: googleapis/google-cloud-python

Issue:
In datastore.connection.Connection.save_entity, determine how to delete properties
From TODO:

``` python
    # TODO: Is this the right method name?
    # TODO: How do you delete properties? Set them to None?
```

See [`datastore.connection.Connection.save_entity`](https://github.com/GoogleCloudPlatform/gcloud-python/blob/1f2aaf3606802f4f02eeb30e22e1082ef7f4594e/gcloud/datastore/connection.py#L321) for relevant code and #146 for some context.

`git blame` output

```
dec0e7c6 (JJ Geewax 2014-01-28 15:15:40 -0500 321)     # TODO: Is this the right method name?
dec0e7c6 (JJ Geewax 2014-01-28 15:15:40 -0500 322)     # TODO: How do you delete properties? Set them to None?
```

In datastore.connection.Connection.save_entity, determine how to delete properties
From TODO:

``` python
    # TODO: Is this the right method name?
    # TODO: How do you delete properties? Set them to None?
```

See [`datastore.connection.Connection.save_entity`](https://github.com/GoogleCloudPlatform/gcloud-python/blob/1f2aaf3606802f4f02eeb30e22e1082ef7f4594e/gcloud/datastore/connection.py#L321) for relevant code and #146 for some context.

`git blame` output

```
dec0e7c6 (JJ Geewax 2014-01-28 15:15:40 -0500 321)     # TODO: Is this the right method name?
dec0e7c6 (JJ Geewax 2014-01-28 15:15:40 -0500 322)     # TODO: How do you delete properties? Set them to None?
```



Discussion:
The [protobuf API docs](https://cloud.google.com/datastore/docs/concepts/entities) specify that an update / upsert operation "overwrites the existing entity".  Any properties not passed in the 'properties' argument will be dropped.

The name 'save_entity' SGTM.

The [protobuf API docs](https://cloud.google.com/datastore/docs/concepts/entities) specify that an update / upsert operation "overwrites the existing entity".  Any properties not passed in the 'properties' argument will be dropped.

The name 'save_entity' SGTM.


Resolving patch:
diff --git a/gcloud/datastore/connection.py b/gcloud/datastore/connection.py
--- a/gcloud/datastore/connection.py
+++ b/gcloud/datastore/connection.py
@@ -338,6 +338,11 @@ def commit(self, dataset_id, mutation_pb):
     def save_entity(self, dataset_id, key_pb, properties):
         """Save an entity to the Cloud Datastore with the provided properties.
 
+        .. note::
+           Any existing properties for the entity identified by 'key_pb'
+           will be replaced by those passed in 'properties';  properties
+           not passed in 'properties' no longer be set for the entity.
+
         :type dataset_id: string
         :param dataset_id: The dataset in which to save the entity.
 
diff --git a/gcloud/datastore/entity.py b/gcloud/datastore/entity.py
--- a/gcloud/datastore/entity.py
+++ b/gcloud/datastore/entity.py
@@ -187,6 +187,12 @@ def reload(self):
     def save(self):
         """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.
+
         :rtype: :class:`gcloud.datastore.entity.Entity`
         :returns: The entity with a possibly updated Key.
         """


Test patch: