Address sixth part of 451: Implement Key.compare_to_proto to check pb keys against existing.

[dhermes]

Addresses sixth part of #451.

NOTE: This has #461 as a diffbase.

[coveralls]

Coverage remained the same when pulling 031b864 on dhermes:fix-451-part6 into b343acf on GoogleCloudPlatform:master.

[tseaver]

031b864 comments inline on the changeset.

[dhermes]

RE: "Why not pass self._data". That was creep from the killed #445. I rebased and got rid of it.

RE: "Calling Entity.key() twice in Entity.save()". I was trying to use the public API as often as possible. I think we should remove the key() / _key distinction and just make key an attribute.

RE: "Replicating code from helpers.key_from_protobuf". See my comment in the parent issue.

RE: "Server completion of a partial key". ISTM the server will always complete with an ID, hence the name auto_id. @pcostell can you confirm?

[coveralls]

Coverage remained the same when pulling 1778430 on dhermes:fix-451-part6 into 8cb41f6 on GoogleCloudPlatform:master.

[dhermes]

As I look at this more I wonder why Connection.save_entity returns the whole Key pb when the backend assigns an auto ID. Why not just return the assigned ID? (Then this whole PR changes, compare_to_proto doesn't need to be implemented.)

In some sense, we want to check that the entire returned key matches but in another sense, we should trust that the backend has preserved everything except the missing final ID.

@tseaver WDYT?

[tseaver]

I'd prefer not to return the protobuf, and I really don't like the "type variant" return signature. Could we have Connection.save_entity return a tuple, (assigned, new_id). E.g.:

assigned, new_id = connection.save_entity(ds_id, key_pb, properties)
if assigned:
    entity.key = entity.key.complete_key(new_id)

[dhermes]

Good call. On it.

[tseaver]

Travis failure: rename to completed_key was incomplete. :)

[dhermes]

Removed Key.compare_to_proto and made Connection.save_entity have a consistent return type (if you consider None to be valid as type int).

@tseaver PTAL

[coveralls]

Coverage remained the same when pulling a257a9c on dhermes:fix-451-part6 into f0e26b8 on GoogleCloudPlatform:master.

[pcostell]

@dhermes the server will always complete keys when the entity is part of insert_with_auto_id. Otherwise, it will not complete it. If something bad happens the server will throw an error (rather than return an incomplete key).