We are currently solving the following issue within our repository. Here is the issue text:
--- BEGIN ISSUE ---
Document "text" vs. "bytes" values for Entities
Docs need to explain clearly how users can ensure that the values they set onto entities get mapped as they expect:  "text" values should be mapped to/from 'string_value' entries on the protobufs, and "bytes" values should be mapped to/from 'blob_value' entries.

We are to have to educate folks that the native 'str' is "bytes" on Python2, but "text" on Python3, and mandate that they be explicit if they want to control how such values get stored.

Document "text" vs. "bytes" values for Entities
Docs need to explain clearly how users can ensure that the values they set onto entities get mapped as they expect:  "text" values should be mapped to/from 'string_value' entries on the protobufs, and "bytes" values should be mapped to/from 'blob_value' entries.

We are to have to educate folks that the native 'str' is "bytes" on Python2, but "text" on Python3, and mandate that they be explicit if they want to control how such values get stored.


--- END ISSUE ---

Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
--- BEGIN FILES ---
Path: `gcloud/datastore/entity.py`
Content:
```
1 """Class for representing a single entity in the Cloud Datastore.
2 
3 Entities are akin to rows in a relational database,
4 storing the actual instance of data.
5 
6 Each entity is officially represented with
7 a :class:`gcloud.datastore.key.Key` class,
8 however it is possible that you might create
9 an Entity with only a partial Key
10 (that is, a Key with a Kind,
11 and possibly a parent, but without an ID).
12 
13 Entities in this API act like dictionaries
14 with extras built in that allow you to
15 delete or persist the data stored on the entity.
16 """
17 
18 from gcloud.datastore import datastore_v1_pb2 as datastore_pb
19 from gcloud.datastore.key import Key
20 
21 
22 class NoKey(RuntimeError):
23     """Exception raised by Entity methods which require a key."""
24 
25 
26 class NoDataset(RuntimeError):
27     """Exception raised by Entity methods which require a dataset."""
28 
29 
30 class Entity(dict):
31     """:type dataset: :class:`gcloud.datastore.dataset.Dataset`
32     :param dataset: The dataset in which this entity belongs.
33 
34     :type kind: string
35     :param kind: The kind of entity this is, akin to a table name in a
36                  relational database.
37 
38     Entities are mutable and act like a subclass of a dictionary.
39     This means you could take an existing entity and change the key
40     to duplicate the object.
41 
42     This can be used on its own, however it is likely easier to use
43     the shortcut methods provided by :class:`gcloud.datastore.dataset.Dataset`
44     such as:
45 
46     - :func:`gcloud.datastore.dataset.Dataset.entity` to create a new entity.
47 
48       >>> dataset.entity('MyEntityKind')
49       <Entity[{'kind': 'MyEntityKind'}] {}>
50 
51     - :func:`gcloud.datastore.dataset.Dataset.get_entity`
52       to retrieve an existing entity.
53 
54       >>> dataset.get_entity(key)
55       <Entity[{'kind': 'EntityKind', id: 1234}] {'property': 'value'}>
56 
57     You can the set values on the entity
58     just like you would on any other dictionary.
59 
60     >>> entity['age'] = 20
61     >>> entity['name'] = 'JJ'
62     >>> entity
63     <Entity[{'kind': 'EntityKind', id: 1234}] {'age': 20, 'name': 'JJ'}>
64 
65     And you can cast an entity to a regular Python dictionary
66     with the `dict` builtin:
67 
68     >>> dict(entity)
69     {'age': 20, 'name': 'JJ'}
70 
71     """
72 
73     def __init__(self, dataset=None, kind=None):
74         super(Entity, self).__init__()
75         self._dataset = dataset
76         if kind:
77             self._key = Key().kind(kind)
78         else:
79             self._key = None
80 
81     def dataset(self):
82         """Get the :class:`.dataset.Dataset` in which this entity belongs.
83 
84         :rtype: :class:`gcloud.datastore.dataset.Dataset`
85         :returns: The Dataset containing the entity if there is a key,
86                   else None.
87 
88         .. note::
89           This is based on the :class:`gcloud.datastore.key.Key` set on the
90           entity. That means that if you have no key set, the dataset might
91           be `None`. It also means that if you change the key on the entity,
92           this will refer to that key's dataset.
93         """
94         return self._dataset
95 
96     def key(self, key=None):
97         """Get or set the :class:`.datastore.key.Key` on the current entity.
98 
99         :type key: :class:`glcouddatastore.key.Key`
100         :param key: The key you want to set on the entity.
101 
102         :rtype: :class:`gcloud.datastore.key.Key` or :class:`Entity`.
103         :returns: Either the current key (on get) or the current
104                   object (on set).
105 
106         >>> entity.key(my_other_key)  # This returns the original entity.
107         <Entity[{'kind': 'OtherKeyKind', 'id': 1234}] {'property': 'value'}>
108         >>> entity.key()  # This returns the key.
109         <Key[{'kind': 'OtherKeyKind', 'id': 1234}]>
110         """
111 
112         if key is not None:
113             self._key = key
114             return self
115         else:
116             return self._key
117 
118     def kind(self):
119         """Get the kind of the current entity.
120 
121         .. note::
122           This relies entirely on
123           the :class:`gcloud.datastore.key.Key`
124           set on the entity.
125           That means that we're not storing the kind of the entity at all,
126           just the properties and a pointer to a Key
127           which knows its Kind.
128         """
129 
130         if self._key:
131             return self._key.kind()
132 
133     @classmethod
134     def from_key(cls, key, dataset=None):
135         """Create entity based on :class:`.datastore.key.Key`.
136 
137         .. note::
138           This is a factory method.
139 
140         :type key: :class:`gcloud.datastore.key.Key`
141         :param key: The key for the entity.
142 
143         :returns: The :class:`Entity` derived from the
144                   :class:`gcloud.datastore.key.Key`.
145         """
146 
147         return cls(dataset).key(key)
148 
149     @property
150     def _must_key(self):
151         """Return our key, or raise NoKey if not set.
152 
153         :rtype: :class:`gcloud.datastore.key.Key`.
154         :returns: our key
155         :raises: NoKey if key is None
156         """
157         if self._key is None:
158             raise NoKey()
159         return self._key
160 
161     @property
162     def _must_dataset(self):
163         """Return our dataset, or raise NoDataset if not set.
164 
165         :rtype: :class:`gcloud.datastore.key.Key`.
166         :returns: our key
167         :raises: NoDataset if key is None
168         """
169         if self._dataset is None:
170             raise NoDataset()
171         return self._dataset
172 
173     def reload(self):
174         """Reloads the contents of this entity from the datastore.
175 
176         This method takes the :class:`gcloud.datastore.key.Key`, loads all
177         properties from the Cloud Datastore, and sets the updated properties on
178         the current object.
179 
180         .. warning::
181           This will override any existing properties if a different value
182           exists remotely, however it will *not* override any properties that
183           exist only locally.
184         """
185         key = self._must_key
186         dataset = self._must_dataset
187         entity = dataset.get_entity(key.to_protobuf())
188 
189         if entity:
190             self.update(entity)
191         return self
192 
193     def save(self):
194         """Save the entity in the Cloud Datastore.
195 
196         .. note::
197            Any existing properties for the entity will be replaced by those
198            currently set on this instance.  Already-stored properties which do
199            not correspond to keys set on this instance will be removed from
200            the datastore.
201 
202         .. note::
203            Property values which are "text" ('unicode' in Python2, 'str' in
204            Python3) map to 'string_value' in the datastore;  values which are
205            "bytes" ('str' in Python2, 'bytes' in Python3) map to 'blob_value'.
206 
207         :rtype: :class:`gcloud.datastore.entity.Entity`
208         :returns: The entity with a possibly updated Key.
209         """
210         key = self._must_key
211         dataset = self._must_dataset
212         connection = dataset.connection()
213         key_pb = connection.save_entity(
214             dataset_id=dataset.id(),
215             key_pb=key.to_protobuf(),
216             properties=dict(self))
217 
218         # If we are in a transaction and the current entity needs an
219         # automatically assigned ID, tell the transaction where to put that.
220         transaction = connection.transaction()
221         if transaction and key.is_partial():
222             transaction.add_auto_id_entity(self)
223 
224         if isinstance(key_pb, datastore_pb.Key):
225             # Update the path (which may have been altered).
226             # NOTE: The underlying namespace can't have changed in a save().
227             #       The value of the dataset ID may have changed from implicit
228             #       (i.e. None, with the ID implied from the dataset.Dataset
229             #       object associated with the Entity/Key), but if it was
230             #       implicit before the save() we leave it as implicit.
231             path = []
232             for element in key_pb.path_element:
233                 key_part = {}
234                 for descriptor, value in element._fields.items():
235                     key_part[descriptor.name] = value
236                 path.append(key_part)
237             self._key = key.path(path)
238 
239         return self
240 
241     def delete(self):
242         """Delete the entity in the Cloud Datastore.
243 
244         .. note::
245           This is based entirely off of the :class:`gcloud.datastore.key.Key`
246           set on the entity. Whatever is stored remotely using the key on the
247           entity will be deleted.
248         """
249         key = self._must_key
250         dataset = self._must_dataset
251         dataset.connection().delete_entities(
252             dataset_id=dataset.id(),
253             key_pbs=[key.to_protobuf()],
254             )
255 
256     def __repr__(self):
257         if self._key:
258             return '<Entity%s %s>' % (self._key.path(),
259                                       super(Entity, self).__repr__())
260         else:
261             return '<Entity %s>' % (super(Entity, self).__repr__())
262
```
--- END FILES ---

Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.

Here is an example:

```diff
diff --git a/examples/server_async.py b/examples/server_async.py
--- a/examples/server_async.py
+++ b/examples/server_async.py
@@ -313,4 +313,4 @@
 
 
 if __name__ == "__main__":
-    asyncio.run(run_async_server("."), debug=True)
+    asyncio.run(run_async_server(), debug=True)
diff --git a/examples/server_sync.py b/examples/server_sync.py
--- a/examples/server_sync.py
+++ b/examples/server_sync.py
@@ -313,5 +313,5 @@
 
 
 if __name__ == "__main__":
-    server = run_sync_server(".")
+    server = run_sync_server()
     server.shutdown()

```

diff --git a/gcloud/datastore/entity.py b/gcloud/datastore/entity.py
--- a/gcloud/datastore/entity.py
+++ b/gcloud/datastore/entity.py
@@ -68,6 +68,16 @@
     >>> dict(entity)
     {'age': 20, 'name': 'JJ'}
 
+    .. note::
+
+       When saving an entity to the backend, values which are "text"
+       ('unicode' in Python2, 'str' in Python3) will be saved using
+       the 'text_value' field, after being encoded to UTF-8.  When
+       retrieved from the back-end, such values will be decoded to "text"
+       again.  Values which are "bytes" ('str' in Python2, 'bytes' in
+       Python3), will be saved using the 'blob_value' field, without
+       any decoding / encoding step.
+
     """
 
     def __init__(self, dataset=None, kind=None):

{"golden_diff": "diff --git a/gcloud/datastore/entity.py b/gcloud/datastore/entity.py\n--- a/gcloud/datastore/entity.py\n+++ b/gcloud/datastore/entity.py\n@@ -68,6 +68,16 @@\n     >>> dict(entity)\n     {'age': 20, 'name': 'JJ'}\n \n+    .. note::\n+\n+       When saving an entity to the backend, values which are \"text\"\n+       ('unicode' in Python2, 'str' in Python3) will be saved using\n+       the 'text_value' field, after being encoded to UTF-8.  When\n+       retrieved from the back-end, such values will be decoded to \"text\"\n+       again.  Values which are \"bytes\" ('str' in Python2, 'bytes' in\n+       Python3), will be saved using the 'blob_value' field, without\n+       any decoding / encoding step.\n+\n     \"\"\"\n \n     def __init__(self, dataset=None, kind=None):\n", "issue": "Document \"text\" vs. \"bytes\" values for Entities\nDocs need to explain clearly how users can ensure that the values they set onto entities get mapped as they expect:  \"text\" values should be mapped to/from 'string_value' entries on the protobufs, and \"bytes\" values should be mapped to/from 'blob_value' entries.\n\nWe are to have to educate folks that the native 'str' is \"bytes\" on Python2, but \"text\" on Python3, and mandate that they be explicit if they want to control how such values get stored.\n\nDocument \"text\" vs. \"bytes\" values for Entities\nDocs need to explain clearly how users can ensure that the values they set onto entities get mapped as they expect:  \"text\" values should be mapped to/from 'string_value' entries on the protobufs, and \"bytes\" values should be mapped to/from 'blob_value' entries.\n\nWe are to have to educate folks that the native 'str' is \"bytes\" on Python2, but \"text\" on Python3, and mandate that they be explicit if they want to control how such values get stored.\n\n", "before_files": [{"content": "\"\"\"Class for representing a single entity in the Cloud Datastore.\n\nEntities are akin to rows in a relational database,\nstoring the actual instance of data.\n\nEach entity is officially represented with\na :class:`gcloud.datastore.key.Key` class,\nhowever it is possible that you might create\nan Entity with only a partial Key\n(that is, a Key with a Kind,\nand possibly a parent, but without an ID).\n\nEntities in this API act like dictionaries\nwith extras built in that allow you to\ndelete or persist the data stored on the entity.\n\"\"\"\n\nfrom gcloud.datastore import datastore_v1_pb2 as datastore_pb\nfrom gcloud.datastore.key import Key\n\n\nclass NoKey(RuntimeError):\n    \"\"\"Exception raised by Entity methods which require a key.\"\"\"\n\n\nclass NoDataset(RuntimeError):\n    \"\"\"Exception raised by Entity methods which require a dataset.\"\"\"\n\n\nclass Entity(dict):\n    \"\"\":type dataset: :class:`gcloud.datastore.dataset.Dataset`\n    :param dataset: The dataset in which this entity belongs.\n\n    :type kind: string\n    :param kind: The kind of entity this is, akin to a table name in a\n                 relational database.\n\n    Entities are mutable and act like a subclass of a dictionary.\n    This means you could take an existing entity and change the key\n    to duplicate the object.\n\n    This can be used on its own, however it is likely easier to use\n    the shortcut methods provided by :class:`gcloud.datastore.dataset.Dataset`\n    such as:\n\n    - :func:`gcloud.datastore.dataset.Dataset.entity` to create a new entity.\n\n      >>> dataset.entity('MyEntityKind')\n      <Entity[{'kind': 'MyEntityKind'}] {}>\n\n    - :func:`gcloud.datastore.dataset.Dataset.get_entity`\n      to retrieve an existing entity.\n\n      >>> dataset.get_entity(key)\n      <Entity[{'kind': 'EntityKind', id: 1234}] {'property': 'value'}>\n\n    You can the set values on the entity\n    just like you would on any other dictionary.\n\n    >>> entity['age'] = 20\n    >>> entity['name'] = 'JJ'\n    >>> entity\n    <Entity[{'kind': 'EntityKind', id: 1234}] {'age': 20, 'name': 'JJ'}>\n\n    And you can cast an entity to a regular Python dictionary\n    with the `dict` builtin:\n\n    >>> dict(entity)\n    {'age': 20, 'name': 'JJ'}\n\n    \"\"\"\n\n    def __init__(self, dataset=None, kind=None):\n        super(Entity, self).__init__()\n        self._dataset = dataset\n        if kind:\n            self._key = Key().kind(kind)\n        else:\n            self._key = None\n\n    def dataset(self):\n        \"\"\"Get the :class:`.dataset.Dataset` in which this entity belongs.\n\n        :rtype: :class:`gcloud.datastore.dataset.Dataset`\n        :returns: The Dataset containing the entity if there is a key,\n                  else None.\n\n        .. note::\n          This is based on the :class:`gcloud.datastore.key.Key` set on the\n          entity. That means that if you have no key set, the dataset might\n          be `None`. It also means that if you change the key on the entity,\n          this will refer to that key's dataset.\n        \"\"\"\n        return self._dataset\n\n    def key(self, key=None):\n        \"\"\"Get or set the :class:`.datastore.key.Key` on the current entity.\n\n        :type key: :class:`glcouddatastore.key.Key`\n        :param key: The key you want to set on the entity.\n\n        :rtype: :class:`gcloud.datastore.key.Key` or :class:`Entity`.\n        :returns: Either the current key (on get) or the current\n                  object (on set).\n\n        >>> entity.key(my_other_key)  # This returns the original entity.\n        <Entity[{'kind': 'OtherKeyKind', 'id': 1234}] {'property': 'value'}>\n        >>> entity.key()  # This returns the key.\n        <Key[{'kind': 'OtherKeyKind', 'id': 1234}]>\n        \"\"\"\n\n        if key is not None:\n            self._key = key\n            return self\n        else:\n            return self._key\n\n    def kind(self):\n        \"\"\"Get the kind of the current entity.\n\n        .. note::\n          This relies entirely on\n          the :class:`gcloud.datastore.key.Key`\n          set on the entity.\n          That means that we're not storing the kind of the entity at all,\n          just the properties and a pointer to a Key\n          which knows its Kind.\n        \"\"\"\n\n        if self._key:\n            return self._key.kind()\n\n    @classmethod\n    def from_key(cls, key, dataset=None):\n        \"\"\"Create entity based on :class:`.datastore.key.Key`.\n\n        .. note::\n          This is a factory method.\n\n        :type key: :class:`gcloud.datastore.key.Key`\n        :param key: The key for the entity.\n\n        :returns: The :class:`Entity` derived from the\n                  :class:`gcloud.datastore.key.Key`.\n        \"\"\"\n\n        return cls(dataset).key(key)\n\n    @property\n    def _must_key(self):\n        \"\"\"Return our key, or raise NoKey if not set.\n\n        :rtype: :class:`gcloud.datastore.key.Key`.\n        :returns: our key\n        :raises: NoKey if key is None\n        \"\"\"\n        if self._key is None:\n            raise NoKey()\n        return self._key\n\n    @property\n    def _must_dataset(self):\n        \"\"\"Return our dataset, or raise NoDataset if not set.\n\n        :rtype: :class:`gcloud.datastore.key.Key`.\n        :returns: our key\n        :raises: NoDataset if key is None\n        \"\"\"\n        if self._dataset is None:\n            raise NoDataset()\n        return self._dataset\n\n    def reload(self):\n        \"\"\"Reloads the contents of this entity from the datastore.\n\n        This method takes the :class:`gcloud.datastore.key.Key`, loads all\n        properties from the Cloud Datastore, and sets the updated properties on\n        the current object.\n\n        .. warning::\n          This will override any existing properties if a different value\n          exists remotely, however it will *not* override any properties that\n          exist only locally.\n        \"\"\"\n        key = self._must_key\n        dataset = self._must_dataset\n        entity = dataset.get_entity(key.to_protobuf())\n\n        if entity:\n            self.update(entity)\n        return self\n\n    def save(self):\n        \"\"\"Save the entity in the Cloud Datastore.\n\n        .. note::\n           Any existing properties for the entity will be replaced by those\n           currently set on this instance.  Already-stored properties which do\n           not correspond to keys set on this instance will be removed from\n           the datastore.\n\n        .. note::\n           Property values which are \"text\" ('unicode' in Python2, 'str' in\n           Python3) map to 'string_value' in the datastore;  values which are\n           \"bytes\" ('str' in Python2, 'bytes' in Python3) map to 'blob_value'.\n\n        :rtype: :class:`gcloud.datastore.entity.Entity`\n        :returns: The entity with a possibly updated Key.\n        \"\"\"\n        key = self._must_key\n        dataset = self._must_dataset\n        connection = dataset.connection()\n        key_pb = connection.save_entity(\n            dataset_id=dataset.id(),\n            key_pb=key.to_protobuf(),\n            properties=dict(self))\n\n        # If we are in a transaction and the current entity needs an\n        # automatically assigned ID, tell the transaction where to put that.\n        transaction = connection.transaction()\n        if transaction and key.is_partial():\n            transaction.add_auto_id_entity(self)\n\n        if isinstance(key_pb, datastore_pb.Key):\n            # Update the path (which may have been altered).\n            # NOTE: The underlying namespace can't have changed in a save().\n            #       The value of the dataset ID may have changed from implicit\n            #       (i.e. None, with the ID implied from the dataset.Dataset\n            #       object associated with the Entity/Key), but if it was\n            #       implicit before the save() we leave it as implicit.\n            path = []\n            for element in key_pb.path_element:\n                key_part = {}\n                for descriptor, value in element._fields.items():\n                    key_part[descriptor.name] = value\n                path.append(key_part)\n            self._key = key.path(path)\n\n        return self\n\n    def delete(self):\n        \"\"\"Delete the entity in the Cloud Datastore.\n\n        .. note::\n          This is based entirely off of the :class:`gcloud.datastore.key.Key`\n          set on the entity. Whatever is stored remotely using the key on the\n          entity will be deleted.\n        \"\"\"\n        key = self._must_key\n        dataset = self._must_dataset\n        dataset.connection().delete_entities(\n            dataset_id=dataset.id(),\n            key_pbs=[key.to_protobuf()],\n            )\n\n    def __repr__(self):\n        if self._key:\n            return '<Entity%s %s>' % (self._key.path(),\n                                      super(Entity, self).__repr__())\n        else:\n            return '<Entity %s>' % (super(Entity, self).__repr__())\n", "path": "gcloud/datastore/entity.py"}], "after_files": [{"content": "\"\"\"Class for representing a single entity in the Cloud Datastore.\n\nEntities are akin to rows in a relational database,\nstoring the actual instance of data.\n\nEach entity is officially represented with\na :class:`gcloud.datastore.key.Key` class,\nhowever it is possible that you might create\nan Entity with only a partial Key\n(that is, a Key with a Kind,\nand possibly a parent, but without an ID).\n\nEntities in this API act like dictionaries\nwith extras built in that allow you to\ndelete or persist the data stored on the entity.\n\"\"\"\n\nfrom gcloud.datastore import datastore_v1_pb2 as datastore_pb\nfrom gcloud.datastore.key import Key\n\n\nclass NoKey(RuntimeError):\n    \"\"\"Exception raised by Entity methods which require a key.\"\"\"\n\n\nclass NoDataset(RuntimeError):\n    \"\"\"Exception raised by Entity methods which require a dataset.\"\"\"\n\n\nclass Entity(dict):\n    \"\"\":type dataset: :class:`gcloud.datastore.dataset.Dataset`\n    :param dataset: The dataset in which this entity belongs.\n\n    :type kind: string\n    :param kind: The kind of entity this is, akin to a table name in a\n                 relational database.\n\n    Entities are mutable and act like a subclass of a dictionary.\n    This means you could take an existing entity and change the key\n    to duplicate the object.\n\n    This can be used on its own, however it is likely easier to use\n    the shortcut methods provided by :class:`gcloud.datastore.dataset.Dataset`\n    such as:\n\n    - :func:`gcloud.datastore.dataset.Dataset.entity` to create a new entity.\n\n      >>> dataset.entity('MyEntityKind')\n      <Entity[{'kind': 'MyEntityKind'}] {}>\n\n    - :func:`gcloud.datastore.dataset.Dataset.get_entity`\n      to retrieve an existing entity.\n\n      >>> dataset.get_entity(key)\n      <Entity[{'kind': 'EntityKind', id: 1234}] {'property': 'value'}>\n\n    You can the set values on the entity\n    just like you would on any other dictionary.\n\n    >>> entity['age'] = 20\n    >>> entity['name'] = 'JJ'\n    >>> entity\n    <Entity[{'kind': 'EntityKind', id: 1234}] {'age': 20, 'name': 'JJ'}>\n\n    And you can cast an entity to a regular Python dictionary\n    with the `dict` builtin:\n\n    >>> dict(entity)\n    {'age': 20, 'name': 'JJ'}\n\n    .. note::\n\n       When saving an entity to the backend, values which are \"text\"\n       ('unicode' in Python2, 'str' in Python3) will be saved using\n       the 'text_value' field, after being encoded to UTF-8.  When\n       retrieved from the back-end, such values will be decoded to \"text\"\n       again.  Values which are \"bytes\" ('str' in Python2, 'bytes' in\n       Python3), will be saved using the 'blob_value' field, without\n       any decoding / encoding step.\n\n    \"\"\"\n\n    def __init__(self, dataset=None, kind=None):\n        super(Entity, self).__init__()\n        self._dataset = dataset\n        if kind:\n            self._key = Key().kind(kind)\n        else:\n            self._key = None\n\n    def dataset(self):\n        \"\"\"Get the :class:`.dataset.Dataset` in which this entity belongs.\n\n        :rtype: :class:`gcloud.datastore.dataset.Dataset`\n        :returns: The Dataset containing the entity if there is a key,\n                  else None.\n\n        .. note::\n          This is based on the :class:`gcloud.datastore.key.Key` set on the\n          entity. That means that if you have no key set, the dataset might\n          be `None`. It also means that if you change the key on the entity,\n          this will refer to that key's dataset.\n        \"\"\"\n        return self._dataset\n\n    def key(self, key=None):\n        \"\"\"Get or set the :class:`.datastore.key.Key` on the current entity.\n\n        :type key: :class:`glcouddatastore.key.Key`\n        :param key: The key you want to set on the entity.\n\n        :rtype: :class:`gcloud.datastore.key.Key` or :class:`Entity`.\n        :returns: Either the current key (on get) or the current\n                  object (on set).\n\n        >>> entity.key(my_other_key)  # This returns the original entity.\n        <Entity[{'kind': 'OtherKeyKind', 'id': 1234}] {'property': 'value'}>\n        >>> entity.key()  # This returns the key.\n        <Key[{'kind': 'OtherKeyKind', 'id': 1234}]>\n        \"\"\"\n\n        if key is not None:\n            self._key = key\n            return self\n        else:\n            return self._key\n\n    def kind(self):\n        \"\"\"Get the kind of the current entity.\n\n        .. note::\n          This relies entirely on\n          the :class:`gcloud.datastore.key.Key`\n          set on the entity.\n          That means that we're not storing the kind of the entity at all,\n          just the properties and a pointer to a Key\n          which knows its Kind.\n        \"\"\"\n\n        if self._key:\n            return self._key.kind()\n\n    @classmethod\n    def from_key(cls, key, dataset=None):\n        \"\"\"Create entity based on :class:`.datastore.key.Key`.\n\n        .. note::\n          This is a factory method.\n\n        :type key: :class:`gcloud.datastore.key.Key`\n        :param key: The key for the entity.\n\n        :returns: The :class:`Entity` derived from the\n                  :class:`gcloud.datastore.key.Key`.\n        \"\"\"\n\n        return cls(dataset).key(key)\n\n    @property\n    def _must_key(self):\n        \"\"\"Return our key, or raise NoKey if not set.\n\n        :rtype: :class:`gcloud.datastore.key.Key`.\n        :returns: our key\n        :raises: NoKey if key is None\n        \"\"\"\n        if self._key is None:\n            raise NoKey()\n        return self._key\n\n    @property\n    def _must_dataset(self):\n        \"\"\"Return our dataset, or raise NoDataset if not set.\n\n        :rtype: :class:`gcloud.datastore.key.Key`.\n        :returns: our key\n        :raises: NoDataset if key is None\n        \"\"\"\n        if self._dataset is None:\n            raise NoDataset()\n        return self._dataset\n\n    def reload(self):\n        \"\"\"Reloads the contents of this entity from the datastore.\n\n        This method takes the :class:`gcloud.datastore.key.Key`, loads all\n        properties from the Cloud Datastore, and sets the updated properties on\n        the current object.\n\n        .. warning::\n          This will override any existing properties if a different value\n          exists remotely, however it will *not* override any properties that\n          exist only locally.\n        \"\"\"\n        key = self._must_key\n        dataset = self._must_dataset\n        entity = dataset.get_entity(key.to_protobuf())\n\n        if entity:\n            self.update(entity)\n        return self\n\n    def save(self):\n        \"\"\"Save the entity in the Cloud Datastore.\n\n        .. note::\n           Any existing properties for the entity will be replaced by those\n           currently set on this instance.  Already-stored properties which do\n           not correspond to keys set on this instance will be removed from\n           the datastore.\n\n        .. note::\n           Property values which are \"text\" ('unicode' in Python2, 'str' in\n           Python3) map to 'string_value' in the datastore;  values which are\n           \"bytes\" ('str' in Python2, 'bytes' in Python3) map to 'blob_value'.\n\n        :rtype: :class:`gcloud.datastore.entity.Entity`\n        :returns: The entity with a possibly updated Key.\n        \"\"\"\n        key = self._must_key\n        dataset = self._must_dataset\n        connection = dataset.connection()\n        key_pb = connection.save_entity(\n            dataset_id=dataset.id(),\n            key_pb=key.to_protobuf(),\n            properties=dict(self))\n\n        # If we are in a transaction and the current entity needs an\n        # automatically assigned ID, tell the transaction where to put that.\n        transaction = connection.transaction()\n        if transaction and key.is_partial():\n            transaction.add_auto_id_entity(self)\n\n        if isinstance(key_pb, datastore_pb.Key):\n            # Update the path (which may have been altered).\n            # NOTE: The underlying namespace can't have changed in a save().\n            #       The value of the dataset ID may have changed from implicit\n            #       (i.e. None, with the ID implied from the dataset.Dataset\n            #       object associated with the Entity/Key), but if it was\n            #       implicit before the save() we leave it as implicit.\n            path = []\n            for element in key_pb.path_element:\n                key_part = {}\n                for descriptor, value in element._fields.items():\n                    key_part[descriptor.name] = value\n                path.append(key_part)\n            self._key = key.path(path)\n\n        return self\n\n    def delete(self):\n        \"\"\"Delete the entity in the Cloud Datastore.\n\n        .. note::\n          This is based entirely off of the :class:`gcloud.datastore.key.Key`\n          set on the entity. Whatever is stored remotely using the key on the\n          entity will be deleted.\n        \"\"\"\n        key = self._must_key\n        dataset = self._must_dataset\n        dataset.connection().delete_entities(\n            dataset_id=dataset.id(),\n            key_pbs=[key.to_protobuf()],\n            )\n\n    def __repr__(self):\n        if self._key:\n            return '<Entity%s %s>' % (self._key.path(),\n                                      super(Entity, self).__repr__())\n        else:\n            return '<Entity %s>' % (super(Entity, self).__repr__())\n", "path": "gcloud/datastore/entity.py"}]}