diff --git a/src/crate/client/doctests/blob.txt b/docs/by-example/blob.rst similarity index 85% rename from src/crate/client/doctests/blob.txt rename to docs/by-example/blob.rst index f04b27f99..6169903fe 100644 --- a/src/crate/client/doctests/blob.txt +++ b/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 diff --git a/src/crate/client/doctests/client.txt b/docs/by-example/client.rst similarity index 100% rename from src/crate/client/doctests/client.txt rename to docs/by-example/client.rst diff --git a/src/crate/client/doctests/http.txt b/docs/by-example/http.rst similarity index 100% rename from src/crate/client/doctests/http.txt rename to docs/by-example/http.rst diff --git a/docs/by-example/index.rst b/docs/by-example/index.rst new file mode 100644 index 000000000..820fc4e7a --- /dev/null +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index a31fa7f57..da8df4c06 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -36,6 +36,7 @@ A :ref:`CrateDB dialect ` for `SQLAlchemy`_ is also included. query blobs sqlalchemy + by-example/index appendices/index .. _CrateDB: https://crate.io/products/cratedb/ diff --git a/src/crate/client/doctests/mocking.txt b/src/crate/client/doctests/mocking.txt deleted file mode 100644 index c32a701bb..000000000 --- a/src/crate/client/doctests/mocking.txt +++ /dev/null @@ -1,20 +0,0 @@ -============== -Client Mocking -============== - -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:: - - >>> from crate import client - >>> 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 = client.connect([crate_host], client=MyConnectionClient()) diff --git a/src/crate/client/test_connection.py b/src/crate/client/test_connection.py index 078f88c85..ab9883160 100644 --- a/src/crate/client/test_connection.py +++ b/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'), diff --git a/src/crate/client/tests.py b/src/crate/client/tests.py index 33fe453f1..4ce60ee41 100644 --- a/src/crate/client/tests.py +++ b/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, diff --git a/src/crate/testing/util.py b/src/crate/testing/settings.py similarity index 100% rename from src/crate/testing/util.py rename to src/crate/testing/settings.py diff --git a/src/crate/testing/test_layer.py b/src/crate/testing/test_layer.py index cc17c928a..b4001f512 100644 --- a/src/crate/testing/test_layer.py +++ b/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): diff --git a/src/crate/testing/tests.py b/src/crate/testing/tests.py index 1f77d2de1..b647bc13c 100644 --- a/src/crate/testing/tests.py +++ b/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):