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

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

@@ -1,8 +1,8 @@
-============
-Client Usage
-============
+===============
+Database client
+===============
 
-Connect to a Database
+Connect to a database
 =====================
 
 Before we can start we have to import the client::

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

@@ -1,6 +1,6 @@
-=================
-HTTP Crate Client
-=================
+===========
+HTTP client
+===========
 
 Server configuration
 ====================
@@ -159,10 +159,8 @@ Uploading a blob to a table with disabled blob support throws an exception::
 Error Handling
 ==============
 
-.. hide::
-
-    Create a function that takes a lot of time to return so we can run into a
-    timeout exception::
+Create a function that takes a lot of time to return so we can run into a
+timeout exception::
 
     >>> http_client = HttpClient(crate_host)
     >>> http_client.sql('''

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/util.py → src/crate/testing/settings.py

@@ -19,6 +19,7 @@
 # However, if you have executed another commercial license agreement
 # with Crate these terms will supersede the license and you may use the
 # software solely pursuant to the terms of the relevant commercial agreement.
+from __future__ import absolute_import
 
 import os
 
@@ -41,3 +42,10 @@ def crate_path(*parts):
     return os.path.abspath(
         project_root("parts", "crate", *parts)
     )
+
+
+crate_port = 44209
+crate_transport_port = 44309
+localhost = '127.0.0.1'
+crate_host = "{host}:{port}".format(host=localhost, port=crate_port)
+crate_uri = "http://%s" % crate_host

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):