Merge pull request #1517 from dhermes/fix-1378

Update datastore docstrings to use client pattern.

Author: dhermes

gcloud/datastore/__init__.py

@@ -17,7 +17,7 @@
 You'll typically use these to get started with the API:
 
 >>> from gcloud import datastore
-
+>>>
 >>> client = datastore.Client()
 >>> key = client.key('EntityKind', 1234)
 >>> entity = datastore.Entity(key)

gcloud/datastore/batch.py

@@ -35,8 +35,9 @@ class Batch(object):
     operations and the ``delete`` operation into the same mutation, and send
     them to the server in a single API request::
 
-      >>> from gcloud.datastore.batch import Batch
-      >>> batch = Batch()
+      >>> from gcloud import datastore
+      >>> client = datastore.Client()
+      >>> batch = client.batch()
       >>> batch.put(entity1)
       >>> batch.put(entity2)
       >>> batch.delete(key3)
@@ -46,14 +47,14 @@ class Batch(object):
     :meth:`commit` will be called automatically if its block exits without
     raising an exception::
 
-      >>> with Batch() as batch:
+      >>> with batch:
       ...     batch.put(entity1)
       ...     batch.put(entity2)
       ...     batch.delete(key3)
 
     By default, no updates will be sent if the block exits with an error::
 
-      >>> with Batch() as batch:
+      >>> with batch:
       ...     do_some_work(batch)
       ...     raise Exception()  # rolls back
 

gcloud/datastore/connection.py

@@ -220,7 +220,8 @@ def run_query(self, project, query_pb, namespace=None,
         uses this method to fetch data:
 
         >>> from gcloud import datastore
-        >>> query = datastore.Query(kind='MyKind')
+        >>> client = datastore.Client()
+        >>> query = client.query(kind='MyKind')
         >>> query.add_filter('property', '=', 'val')
 
         Using the query iterator's

gcloud/datastore/entity.py

@@ -39,7 +39,9 @@ class Entity(dict):
 
     Use :func:`gcloud.datastore.get` to retrieve an existing entity.
 
-      >>> datastore.get(key)
+      >>> from gcloud import datastore
+      >>> client = datastore.Client()
+      >>> client.get(key)
       <Entity[{'kind': 'EntityKind', id: 1234}] {'property': 'value'}>
 
     You can the set values on the entity just like you would on any
@@ -67,9 +69,7 @@ class Entity(dict):
        any decoding / encoding step.
 
     :type key: :class:`gcloud.datastore.key.Key`
-    :param key: Optional key to be set on entity. Required for
-                :func:`gcloud.datastore.put()` and
-                :func:`gcloud.datastore.put_multi()`
+    :param key: Optional key to be set on entity.
 
     :type exclude_from_indexes: tuple of string
     :param exclude_from_indexes: Names of fields whose values are not to be

gcloud/datastore/query.py

@@ -194,7 +194,8 @@ def add_filter(self, property_name, operator, value):
         (ie, ``=``, ``<``, ``<=``, ``>``, ``>=``)::
 
           >>> from gcloud import datastore
-          >>> query = datastore.Query('Person')
+          >>> client = datastore.Client()
+          >>> query = client.query(kind='Person')
           >>> query.add_filter('name', '=', 'James')
           >>> query.add_filter('age', '>', 50)
 
@@ -311,7 +312,8 @@ def fetch(self, limit=None, offset=0, start_cursor=None, end_cursor=None,
         For example::
 
           >>> from gcloud import datastore
-          >>> query = datastore.Query('Person')
+          >>> client = datastore.Client()
+          >>> query = client.query(kind='Person')
           >>> query.add_filter('name', '=', 'Sally')
           >>> list(query.fetch())
           [<Entity object>, <Entity object>, ...]

gcloud/datastore/transaction.py

@@ -28,21 +28,21 @@ class Transaction(Batch):
     mutation, and execute those within a transaction::
 
       >>> from gcloud import datastore
-
-      >>> with datastore.Transaction():
-      ...     datastore.put_multi([entity1, entity2])
+      >>> client = datastore.Client()
+      >>> with client.transaction():
+      ...     client.put_multi([entity1, entity2])
 
     Because it derives from :class:`Batch <.datastore.batch.Batch>`,
     :class:`Transaction` also provides :meth:`put` and :meth:`delete` methods::
 
-      >>> with datastore.Transaction() as xact:
+      >>> with client.transaction() as xact:
       ...     xact.put(entity1)
       ...     xact.delete(entity2.key)
 
     By default, the transaction is rolled back if the transaction block
     exits with an error::
 
-      >>> with datastore.Transaction():
+      >>> with client.transaction():
       ...     do_some_work()
       ...     raise SomeException()  # rolls back
 
@@ -53,34 +53,34 @@ class Transaction(Batch):
        entities will not be available at save time!  That means, if you
        try::
 
-         >>> with datastore.Transaction():
-         ...     entity = datastore.Entity(key=Key('Thing'))
-         ...     datastore.put(entity)
+         >>> with client.transaction():
+         ...     entity = datastore.Entity(key=client.key('Thing'))
+         ...     client.put(entity)
 
-       ``entity`` won't have a complete Key until the transaction is
+       ``entity`` won't have a complete key until the transaction is
        committed.
 
        Once you exit the transaction (or call :meth:`commit`), the
        automatically generated ID will be assigned to the entity::
 
-         >>> with datastore.Transaction():
-         ...     entity = datastore.Entity(key=Key('Thing'))
-         ...     datastore.put(entity)
-         ...     print entity.key.is_partial  # There is no ID on this key.
+         >>> with client.transaction():
+         ...     entity = datastore.Entity(key=client.key('Thing'))
+         ...     client.put(entity)
+         ...     print(entity.key.is_partial)  # There is no ID on this key.
          ...
          True
-         >>> print entity.key.is_partial  # There *is* an ID.
+         >>> print(entity.key.is_partial)  # There *is* an ID.
          False
 
     If you don't want to use the context manager you can initialize a
     transaction manually::
 
-      >>> transaction = datastore.Transaction()
+      >>> transaction = client.transaction()
       >>> transaction.begin()
-
-      >>> entity = datastore.Entity(key=Key('Thing'))
+      >>>
+      >>> entity = datastore.Entity(key=client.key('Thing'))
       >>> transaction.put(entity)
-
+      >>>
       >>> if error:
       ...     transaction.rollback()
       ... else: