Adding ability to run doctests with datastore system tests.

datastore/google/cloud/datastore/__init__.py

@@ -16,14 +16,26 @@
 
 You'll typically use these to get started with the API:
 
-.. code-block:: python
+.. testsetup:: constructors
 
- from google.cloud import datastore
+ import os
+ os.environ['GOOGLE_CLOUD_PROJECT'] = u'my-project'
 
- client = datastore.Client()
- key = client.key('EntityKind', 1234)
- entity = datastore.Entity(key)
- query = client.query(kind='EntityKind')
+.. doctest:: constructors
+
+ >>> from google.cloud import datastore
+ >>>
+ >>> client = datastore.Client()
+ >>> print(client.project)
+ my-project
+ >>> key = client.key('EntityKind', 1234)
+ >>> key
+ <Key('EntityKind', 1234), project=my-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/entity.py

@@ -144,7 +144,7 @@ def exclude_from_indexes(self):
 
  def __repr__(self):
  if self.key:
- return '<Entity%s %s>' % (self.key.path,
+ return '<Entity%s %s>' % (self.key._flat_path,
  super(Entity, self).__repr__())
  else:
- return '<Entity %s>' % (super(Entity, self).__repr__())
+ return '<Entity %s>' % (super(Entity, self).__repr__(),)

datastore/google/cloud/datastore/key.py

@@ -380,7 +380,7 @@ def parent(self):
  return self._parent
 
  def __repr__(self):
- return '<Key%s, project=%s>' % (self.path, self.project)
+ return '<Key%s, project=%s>' % (self._flat_path, self.project)
 
 
 def _validate_project(project, parent):

datastore/unit_tests/test_entity.py

@@ -190,10 +190,13 @@ def test___repr___no_key_empty(self):
 
  def test___repr___w_key_non_empty(self):
  key = _Key()
- key._path = '/bar/baz'
+ flat_path = ('bar', 12, 'baz', 'himom')
+ key._flat_path = flat_path
  entity = self._make_one(key=key)
- entity['foo'] = 'Foo'
- self.assertEqual(repr(entity), "<Entity/bar/baz {'foo': 'Foo'}>")
+ entity_vals = {'foo': 'Foo'}
+ entity.update(entity_vals)
+ expected = '<Entity%s %s>' % (flat_path, entity_vals)
+ self.assertEqual(repr(entity), expected)
 
 
 class _Key(object):
@@ -206,7 +209,3 @@ class _Key(object):
 
  def __init__(self, project=_PROJECT):
  self.project = project
-
- @property
- def path(self):
- return self._path

system_tests/datastore.py

@@ -14,6 +14,8 @@
 
 import datetime
 import os
+import pkgutil
+import tempfile
 import unittest
 
 import httplib2
@@ -31,6 +33,23 @@
 from system_test_utils import unique_resource_id
 
 
+SPHINX_CONF = """\
+extensions = [
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.doctest',
+]
+"""
+
+SPHINX_SECTION_TEMPLATE = """\
+Section %02d
+===========
+
+.. automodule:: google.cloud.%s
+ :members:
+
+"""
+
+
 class Config(object):
  """Run-time configuration to be modified at set-up.
 
@@ -495,3 +514,59 @@ def test_failure_with_contention(self):
  # transaction.
  entity_in_txn[contention_prop_name] = u'inside'
  txn.put(entity_in_txn)
+
+
+class TestDoctest(unittest.TestCase):
+
+ def _submodules(self):
+ pkg_iter = pkgutil.iter_modules(datastore.__path__)
+ result = []
+ for _, mod_name, ispkg in pkg_iter:
+ if mod_name == '_generated':
+ self.assertTrue(ispkg)
+ else:
+ self.assertFalse(ispkg)
+ result.append(mod_name)
+
+ self.assertNotIn('__init__', result)
+ return result
+
+ @staticmethod
+ def _add_section(index, mod_name, file_obj):
+ mod_part = 'datastore'
+ if mod_name != '__init__':
+ mod_part += '.' + mod_name
+ content = SPHINX_SECTION_TEMPLATE % (index, mod_part)
+ file_obj.write(content)
+
+ def _make_temp_docs(self):
+ docs_dir = tempfile.mkdtemp(prefix='datastore-')
+
+ conf_file = os.path.join(docs_dir, 'conf.py')
+
+ with open(conf_file, 'w') as file_obj:
+ file_obj.write(SPHINX_CONF)
+
+ index_file = os.path.join(docs_dir, 'contents.rst')
+ datastore_modules = self._submodules()
+ with open(index_file, 'w') as file_obj:
+ self._add_section(0, '__init__', file_obj)
+ for index, datastore_module in enumerate(datastore_modules):
+ self._add_section(index + 1, datastore_module, file_obj)
+
+ return docs_dir
+
+ def test_it(self):
+ from sphinx import application
+
+ docs_dir = self._make_temp_docs()
+ outdir = os.path.join(docs_dir, 'doctest', 'out')
+ doctreedir = os.path.join(docs_dir, 'doctest', 'doctrees')
+
+ app = application.Sphinx(
+ srcdir=docs_dir, confdir=docs_dir,
+ outdir=outdir, doctreedir=doctreedir,
+ buildername='doctest', warningiserror=True, parallel=1)
+
+ app.build()
+ self.assertEqual(app.statuscode, 0)

tox.ini

@@ -265,6 +265,7 @@ commands =
  python {toxinidir}/system_tests/attempt_system_tests.py {posargs}
 deps =
  {[testing]deps}
+ Sphinx
 passenv =
  {[testing]passenv}
  encrypted_*
@@ -273,10 +274,9 @@ passenv =
 basepython =
  python3.4
 commands =
- {[testing]localdeps}
- python {toxinidir}/system_tests/attempt_system_tests.py {posargs}
+ {[testenv:system-tests]commands}
 deps =
- {[testing]deps}
+ {[testenv:system-tests]deps}
 passenv =
  {[testenv:system-tests]passenv}