Merge pull request #297 from tseaver/293-clarify_key_datastore_id_parameter

tseaver · tseaver · commit e1fd94fe7587 · 2014-10-27T22:17:27.000-04:00
Address #293: document that app code should not pass 'dataset_id' to 'Key.__init__'.
diff --git a/gcloud/datastore/key.py b/gcloud/datastore/key.py
@@ -24,7 +24,15 @@ def __init__(self, path=None, namespace=None, dataset_id=None):
 
         :type dataset_id: string
         :param dataset: The dataset ID assigned by back-end for the key.
-                        Leave as None for newly-created keys.
+
+        .. note::
+
+           The key's ``_dataset_id`` field must be None for keys created
+           by application code.  The
+           :func:`gcloud.datastore.helpers.key_from_protobuf` factory
+           will be set the field to an appropriate value for keys returned
+           from the datastore backend.  The application **must** treat any
+           value set by the back-end as opaque.
         """
         self._path = path or [{'kind': ''}]
         self._namespace = namespace
