Tests: Refactor doctests/{client,http,blob}.txt into rst documentation

The referenced doctests are now becoming first citizens of the published
documentation, within a `by-example` section. To make sure they are
always valid, they are still evaluated as doctests.

`doctests/mocking.txt` has been translated into a pure-Python test case.

src/crate/client/doctests/blob.txt → docs/by-example/blob.rst

@@ -1,9 +1,9 @@
-==============
-Blob Container
-==============
+==================
+Blob container API
+==================
 
-The connection provides a blob container implementation for easy use of the
-bloba API.
+The connection object provides a convenience API for easy access to `blob
+tables`_.
 
 Create a connection::
 
@@ -18,7 +18,7 @@ Get a blob container::
 Store Blobs
 ===========
 
-The container allows to store a blob without explicitely providing the hash
+The container allows to store a blob without explicitly providing the hash
 for the blob. This feature is possible if the blob is provided as a seekable
 stream like object.
 
@@ -95,3 +95,5 @@ Close the connection to clear the connection pool::
 
  >>> client.close()
 
+
+.. _blob tables: https://crate.io/docs/crate/reference/en/latest/general/blobs.html

docs/by-example/index.rst

@@ -0,0 +1,23 @@
+##########
+By example
+##########
+
+
+*****
+About
+*****
+
+This part of the documentation contains examples how to use the CrateDB Python
+client, exercising different options and scenarios.
+
+
+*******
+Details
+*******
+
+.. toctree::
+ :maxdepth: 2
+
+ client
+ http
+ blob

docs/index.rst

@@ -36,6 +36,7 @@ A :ref:`CrateDB dialect <using-sqlalchemy>` for `SQLAlchemy`_ is also included.
  query
  blobs
  sqlalchemy
+ by-example/index
  appendices/index
 
 .. _CrateDB: https://crate.io/products/cratedb/

src/crate/client/test_connection.py

@@ -1,12 +1,40 @@
 import datetime
 
+from .connection import Connection
 from .http import Client
 from crate.client import connect
 from unittest import TestCase
 
+from ..testing.settings import crate_host
+
 
 class ConnectionTest(TestCase):
 
+ def test_connection_mock(self):
+ """
+ For testing purposes it is often useful to replace the client used for
+ communication with the CrateDB server with a stub or mock.
+
+ This can be done by passing an object of the Client class when calling the
+ ``connect`` method.
+ """
+
+ class MyConnectionClient:
+ active_servers = ["localhost:4200"]
+
+ def __init__(self):
+ pass
+
+ def sql(self, stmt=None, parameters=None):
+ pass
+
+ def server_infos(self, server):
+ return ("localhost:4200", "my server", "0.42.0")
+
+ connection = connect([crate_host], client=MyConnectionClient())
+ self.assertIsInstance(connection, Connection)
+ self.assertEqual(connection.client.server_infos("foo"), ('localhost:4200', 'my server', '0.42.0'))
+
  def test_lowest_server_version(self):
  infos = [(None, None, '0.42.3'),
  (None, None, '0.41.8'),

src/crate/client/tests.py

@@ -37,7 +37,9 @@
 import stopit
 
 from crate.testing.layer import CrateLayer
-from crate.testing.util import crate_path, docs_path
+from crate.testing.settings import \
+ crate_host, crate_path, crate_port, \
+ crate_transport_port, docs_path, localhost
 from crate.client import connect
 from crate.client.sqlalchemy.dialect import CrateDialect
 from crate.client.test_util import ClientMocked
@@ -85,11 +87,6 @@ def setUpMocked(test):
  'auth.host_based.config.99.user': 'me',
  'auth.host_based.config.99.method': 'password',
 }
-crate_port = 44209
-crate_transport_port = 44309
-local = '127.0.0.1'
-crate_host = "{host}:{port}".format(host=local, port=crate_port)
-crate_uri = "http://%s" % crate_host
 crate_layer = None
 
 
@@ -113,7 +110,7 @@ def ensure_cratedb_layer():
  crate_layer = CrateLayer('crate',
  crate_home=crate_path(),
  port=crate_port,
- host=local,
+ host=localhost,
  transport_port=crate_transport_port,
  settings=settings)
  return crate_layer
@@ -381,11 +378,10 @@ def test_suite():
  suite.addTest(s)
 
  s = doctest.DocFileSuite(
- 'doctests/http.txt',
- 'doctests/blob.txt',
- 'doctests/client.txt',
- 'doctests/mocking.txt',
- 'doctests/blob.txt',
+ 'docs/by-example/http.rst',
+ 'docs/by-example/client.rst',
+ 'docs/by-example/blob.rst',
+ module_relative=False,
  setUp=setUpWithCrateLayer,
  tearDown=tearDownWithCrateLayer,
  optionflags=flags,

src/crate/testing/test_layer.py

@@ -30,7 +30,7 @@
 
 import crate
 from .layer import CrateLayer, prepend_http, http_url_from_host_port, wait_for_http_url
-from .util import crate_path
+from .settings import crate_path
 
 
 class LayerUtilsTest(TestCase):

src/crate/testing/tests.py

@@ -24,7 +24,7 @@
 import unittest
 import tempfile
 from .test_layer import LayerUtilsTest, LayerTest
-from .util import project_root, crate_path
+from .settings import project_root, crate_path
 
 
 def setUp(test):