Merge pull request #2831 from dhermes/moar-datastore-doctests

Converting remaining datastore snippets to doctests

datastore/google/cloud/datastore/__init__.py

@@ -18,17 +18,17 @@
 
 .. doctest:: constructors
 
-  >>> from google.cloud import datastore
-  >>>
-  >>> client = datastore.Client()
-  >>> key = client.key('EntityKind', 1234)
-  >>> key
-  <Key('EntityKind', 1234), project=...>
-  >>> entity = datastore.Entity(key)
-  >>> entity['answer'] = 42
-  >>> entity
-  <Entity('EntityKind', 1234) {'answer': 42}>
-  >>> query = client.query(kind='EntityKind')
+   >>> from google.cloud import datastore
+   >>>
+   >>> client = datastore.Client()
+   >>> key = client.key('EntityKind', 1234)
+   >>> key
+   <Key('EntityKind', 1234), project=...>
+   >>> entity = datastore.Entity(key)
+   >>> entity['answer'] = 42
+   >>> entity
+   <Entity('EntityKind', 1234) {'answer': 42}>
+   >>> query = client.query(kind='EntityKind')
 
 The main concepts with this API are:
 

datastore/google/cloud/datastore/client.py

@@ -146,6 +146,11 @@ def _extended_lookup(connection, project, key_pbs,
 class Client(_BaseClient, _ClientProjectMixin):
     """Convenience wrapper for invoking APIs/factories w/ a project.
 
+    .. doctest::
+
+       >>> from google.cloud import datastore
+       >>> client = datastore.Client()
+
     :type project: str
     :param project: (optional) The project to pass to proxied API methods.
 
@@ -449,51 +454,65 @@ def query(self, **kwargs):
 
         Using query to search a datastore:
 
-        .. code-block:: python
+        .. testsetup:: query
+
+           from google.cloud import datastore
+
+           client = datastore.Client()
+           query = client.query(kind='_Doctest')
 
-          >>> from google.cloud import datastore
-          >>> client = datastore.Client()
-          >>> query = client.query(kind='MyKind')
-          >>> query.add_filter('property', '=', 'val')
+           def do_something(entity):
+               pass
+
+        .. doctest:: query
+
+           >>> query = client.query(kind='MyKind')
+           >>> query.add_filter('property', '=', 'val')
 
         Using the query iterator
 
-        .. code-block:: python
+        .. doctest:: query
 
-          >>> query_iter = query.fetch()
-          >>> for entity in query_iter:
-          ...     do_something(entity)
+           >>> query_iter = query.fetch()
+           >>> for entity in query_iter:
+           ...     do_something(entity)
 
         or manually page through results
 
-        .. code-block:: python
+        .. testsetup:: query-page
+
+           from google.cloud import datastore
+           from datastore import Config  # system tests
+
+           client = datastore.Client()
 
-          >>> query_iter = query.fetch(start_cursor='2mdd223i944')
-          >>> pages = query_iter.pages
-          >>>
-          >>> first_page = next(pages)
-          >>> first_page_entities = list(first_page)
-          >>> query_iter.next_page_token
-          'abc-some-cursor'
-          >>>
-          >>> second_page = next(pages)
-          >>> second_page_entities = list(second_page)
-          >>> query_iter.next_page_token is None
-          True
+           key = client.key('_Doctest')
+           entity1 = datastore.Entity(key=key)
+           entity1['foo'] = 1337
+           entity2 = datastore.Entity(key=key)
+           entity2['foo'] = 42
+           Config.TO_DELETE.extend([entity1, entity2])
+           client.put_multi([entity1, entity2])
 
-        Under the hood this is doing:
+           query = client.query(kind='_Doctest')
+           cursor = None
 
-        .. code-block:: python
+        .. doctest:: query-page
 
-          >>> connection.run_query('project', query.to_protobuf())
-          [<list of Entity Protobufs>], cursor, more_results, skipped_results
+           >>> query_iter = query.fetch(start_cursor=cursor)
+           >>> pages = query_iter.pages
+           >>>
+           >>> first_page = next(pages)
+           >>> first_page_entities = list(first_page)
+           >>> query_iter.next_page_token
+           '...'
 
         :type kwargs: dict
         :param kwargs: Parameters for initializing and instance of
-                       :class:`google.cloud.datastore.query.Query`.
+                       :class:`~google.cloud.datastore.query.Query`.
 
-        :rtype: :class:`google.cloud.datastore.query.Query`
-        :returns: An instance of :class:`google.cloud.datastore.query.Query`
+        :rtype: :class:`~google.cloud.datastore.query.Query`
+        :returns: A query object.
         """
         if 'client' in kwargs:
             raise TypeError('Cannot pass client')

datastore/google/cloud/datastore/entity.py

@@ -40,30 +40,48 @@ class Entity(dict):
     Use :meth:`~google.cloud.datastore.client.Client.get` to retrieve an
     existing entity:
 
-    .. code-block:: python
+    .. testsetup:: entity-ctor
 
-      >>> from google.cloud import datastore
-      >>> client = datastore.Client()
-      >>> client.get(key)
-      <Entity[{'kind': 'EntityKind', id: 1234}] {'property': 'value'}>
+       from google.cloud import datastore
+       from datastore import Config  # system tests
+
+       client = datastore.Client()
+       key = client.key('EntityKind', 1234, namespace='_Doctest')
+       entity = datastore.Entity(key=key)
+       entity['property'] = 'value'
+       Config.TO_DELETE.append(entity)
+
+       client.put(entity)
+
+    .. doctest:: entity-ctor
+
+       >>> client.get(key)
+       <Entity(u'EntityKind', 1234L) {u'property': 'value'}>
 
     You can the set values on the entity just like you would on any
     other dictionary.
 
-    .. code-block:: python
+    .. doctest:: entity-ctor
+
+       >>> entity['age'] = 20
+       >>> entity['name'] = 'JJ'
+
+    And you can treat an entity like a regular Python dictionary:
+
+    .. testsetup:: entity-dict
 
-      >>> entity['age'] = 20
-      >>> entity['name'] = 'JJ'
-      >>> entity
-      <Entity[{'kind': 'EntityKind', id: 1234}] {'age': 20, 'name': 'JJ'}>
+       from google.cloud import datastore
 
-    And you can convert an entity to a regular Python dictionary with the
-    ``dict`` builtin:
+       entity = datastore.Entity()
+       entity['age'] = 20
+       entity['name'] = 'JJ'
 
-    .. code-block:: python
+    .. doctest:: entity-dict
 
-      >>> dict(entity)
-      {'age': 20, 'name': 'JJ'}
+       >>> sorted(entity.keys())
+       ['age', 'name']
+       >>> sorted(entity.items())
+       [('age', 20), ('name', 'JJ')]
 
     .. note::
 

datastore/google/cloud/datastore/key.py

@@ -23,30 +23,50 @@
 class Key(object):
     """An immutable representation of a datastore Key.
 
-    To create a basic key:
+    .. testsetup:: key-ctor
 
-    .. code-block:: python
+       from google.cloud import datastore
 
-      >>> Key('EntityKind', 1234)
-      <Key[{'kind': 'EntityKind', 'id': 1234}]>
-      >>> Key('EntityKind', 'foo')
-      <Key[{'kind': 'EntityKind', 'name': 'foo'}]>
+       project = 'my-special-pony'
+       client = datastore.Client(project=project)
+       Key = datastore.Key
+
+       parent_key = client.key('Parent', 'foo')
+
+    To create a basic key directly:
+
+    .. doctest:: key-ctor
+
+       >>> Key('EntityKind', 1234, project=project)
+       <Key('EntityKind', 1234), project=...>
+       >>> Key('EntityKind', 'foo', project=project)
+       <Key('EntityKind', 'foo'), project=...>
+
+    Though typical usage comes via the
+    :meth:`~google.cloud.datastore.client.Client.key` factory:
+
+    .. doctest:: key-ctor
+
+       >>> client.key('EntityKind', 1234)
+       <Key('EntityKind', 1234), project=...>
+       >>> client.key('EntityKind', 'foo')
+       <Key('EntityKind', 'foo'), project=...>
 
     To create a key with a parent:
 
-    .. code-block:: python
+    .. doctest:: key-ctor
 
-      >>> Key('Parent', 'foo', 'Child', 1234)
-      <Key[{'kind': 'Parent', 'name': 'foo'}, {'kind': 'Child', 'id': 1234}]>
-      >>> Key('Child', 1234, parent=parent_key)
-      <Key[{'kind': 'Parent', 'name': 'foo'}, {'kind': 'Child', 'id': 1234}]>
+       >>> client.key('Parent', 'foo', 'Child', 1234)
+       <Key('Parent', 'foo', 'Child', 1234), project=...>
+       >>> client.key('Child', 1234, parent=parent_key)
+       <Key('Parent', 'foo', 'Child', 1234), project=...>
 
     To create a partial key:
 
-    .. code-block:: python
+    .. doctest:: key-ctor
 
-      >>> Key('Parent', 'foo', 'Child')
-      <Key[{'kind': 'Parent', 'name': 'foo'}, {'kind': 'Child'}]>
+       >>> client.key('Parent', 'foo', 'Child')
+       <Key('Parent', 'foo', 'Child'), project=...>
 
     :type path_args: tuple of string and integer
     :param path_args: May represent a partial (odd length) or full (even