Add notes to docstrings about 'text' vs. 'bytes' semantics.

Addresses #233.

Author: tseaver

gcloud/datastore/_helpers.py

@@ -29,6 +29,11 @@ def _get_protobuf_attribute_and_value(val):
     `gcloud.datastore.key.Key` into a Protobuf representation.
     This function handles that for you.
 
+    .. note::
+       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'.
+
     For example:
 
     >>> _get_protobuf_attribute_and_value(1234)

gcloud/datastore/entity.py

@@ -206,6 +206,11 @@ def save(self):
            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'.
+
         :rtype: :class:`gcloud.datastore.entity.Entity`
         :returns: The entity with a possibly updated Key.
         """