From 09228cc28d805cc3ddb61f8f3463eb509ca35b49 Mon Sep 17 00:00:00 2001
From: Danny Hermes <daniel.j.hermes@gmail.com>
Date: Wed, 3 May 2017 11:17:04 -0700
Subject: [PATCH] Add better documentation for support types in datastore
 Entity.

H/T to @GustavoRPS for bringing this up in #3361.

Also snuck in a change in `google.cloud.datastore.helpers` to use
`six.binary_type` in place of `(str, bytes)`. (It wasn't a Py3 error
before because that check came **after** a `six.text_type` check.)
---
 datastore/google/cloud/datastore/entity.py  | 31 +++++++++++++++++++--
 datastore/google/cloud/datastore/helpers.py |  2 +-
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/datastore/google/cloud/datastore/entity.py b/datastore/google/cloud/datastore/entity.py
index a1708c0ca8f6..dc8a60b038be 100644
--- a/datastore/google/cloud/datastore/entity.py
+++ b/datastore/google/cloud/datastore/entity.py
@@ -24,9 +24,9 @@ class Entity(dict):
     An entity storing the actual instance of data.
 
     Each entity is officially represented with a
-    :class:`google.cloud.datastore.key.Key` class, however it is possible that
-    you might create an Entity with only a partial Key (that is, a Key
-    with a Kind, and possibly a parent, but without an ID).  In such a
+    :class:`~google.cloud.datastore.key.Key`, however it is possible that
+    you might create an entity with only a partial key (that is, a key
+    with a kind, and possibly a parent, but without an ID).  In such a
     case, the datastore service will automatically assign an ID to the
     partial key.
 
@@ -66,6 +66,31 @@ class Entity(dict):
        >>> entity['age'] = 20
        >>> entity['name'] = 'JJ'
 
+    However, not all types are allowed as a value for a Google Cloud Datastore
+    entity. The following basic types are supported by the API:
+
+    * :class:`datetime.datetime`
+    * :class:`~google.cloud.datastore.key.Key`
+    * :class:`bool`
+    * :class:`float`
+    * :class:`int` (as well as :class:`long` in Python 2)
+    * ``unicode`` (called ``str`` in Python 3)
+    * ``bytes`` (called ``str`` in Python 2)
+    * :class:`~google.cloud.datastore.helpers.GeoPoint`
+    * :data:`None`
+
+    In addition, two container types are supported:
+
+    * :class:`list`
+    * :class:`~google.cloud.datastore.entity.Entity`
+
+    Each entry in a list must be one of the value types (basic or
+    container) and each value in an
+    :class:`~google.cloud.datastore.entity.Entity` must as well. In
+    this case an :class:`~google.cloud.datastore.entity.Entity` **as a
+    container** acts as a :class:`dict`, but also has the special annotations
+    of ``key`` and ``exclude_from_indexes``.
+
     And you can treat an entity like a regular Python dictionary:
 
     .. testsetup:: entity-dict
diff --git a/datastore/google/cloud/datastore/helpers.py b/datastore/google/cloud/datastore/helpers.py
index 36b11d0f8900..ee4537317030 100644
--- a/datastore/google/cloud/datastore/helpers.py
+++ b/datastore/google/cloud/datastore/helpers.py
@@ -311,7 +311,7 @@ def _pb_attr_value(val):
         name, value = 'integer', val
     elif isinstance(val, six.text_type):
         name, value = 'string', val
-    elif isinstance(val, (bytes, str)):
+    elif isinstance(val, six.binary_type):
         name, value = 'blob', val
     elif isinstance(val, Entity):
         name, value = 'entity', val