Merge "More explicitly document driver connection strings"1.64.2

14 files changed, 160 insertions, 4 deletions

diff --git a/doc/requirements.txt b/doc/requirements.txt
index c286519..c870932 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -10,3 +10,5 @@ redis>=2.10.0 # MIT
 psycopg2>=2.5 # LGPL/ZPL
 PyMySQL>=0.6.2 # MIT License
 pymemcache!=1.3.0,>=1.2.9 # Apache 2.0 License
+etcd3>=0.6.2 # Apache-2.0
+etcd3gw>=0.1.0 # Apache-2.0
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index 15b7d57..830a596 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -20,6 +20,18 @@ Etcd
 .. autoclass:: tooz.drivers.etcd.EtcdDriver
    :members:
 
+Etcd3
+~~~~~
+
+.. autoclass:: tooz.drivers.etcd3.Etcd3Driver
+   :members:
+
+Etcd3gw
+~~~~~~~
+
+.. autoclass:: tooz.drivers.etcd3gw.Etcd3Driver
+   :members:
+
 File
 ~~~~
 
diff --git a/doc/source/user/drivers.rst b/doc/source/user/drivers.rst
index 3d3fdd3..c03d9de 100644
--- a/doc/source/user/drivers.rst
+++ b/doc/source/user/drivers.rst
@@ -198,6 +198,38 @@ The etcd driver is a driver providing only distributed locks (for now)
 and is based on the `etcd server`_ supported key/value storage and
 associated primitives.
 
+Etcd3
+-----
+
+**Driver:**  :py:class:`tooz.drivers.etcd3.Etcd3Driver`
+
+**Characteristics:** :py:attr:`tooz.drivers.etcd3.Etcd3Driver.CHARACTERISTICS`
+
+**Entrypoint name:** ``etcd3``
+
+**Summary:**
+
+The etcd3 driver is a driver providing only distributed locks (for now)
+and is based on the `etcd server`_ supported key/value storage and
+associated primitives.
+
+Etcd3 Gateway
+-------------
+
+**Driver:**  :py:class:`tooz.drivers.etcd3gw.Etcd3Driver`
+
+**Characteristics:**
+:py:attr:`tooz.drivers.etcd3gw.Etcd3Driver.CHARACTERISTICS`
+
+**Entrypoint name:** ``etcd3+http``
+
+**Summary:**
+
+The etcd3gw driver is a driver providing only distributed locks (for now)
+and is based on the `etcd server`_ supported key/value storage and
+associated primitives. It relies on the `GRPC Gateway`_ to provide HTTP access
+to etcd3.
+
 Consul
 ------
 
@@ -231,3 +263,4 @@ Characteristics
 .. _PostgreSQL database server: http://postgresql.org
 .. _MySQL database server: http://mysql.org
 .. _redis-sentinel: http://redis.io/topics/sentinel
+.. _GRPC Gateway: https://github.com/grpc-ecosystem/grpc-gateway
diff --git a/tooz/drivers/consul.py b/tooz/drivers/consul.py
index f9fd559..f5cfd9b 100644
--- a/tooz/drivers/consul.py
+++ b/tooz/drivers/consul.py
@@ -91,10 +91,22 @@ class ConsulDriver(coordination.CoordinationDriver):
     needed to make Consul being used as an option for Distributed Locking. The
     data is stored in Consul's key-value store.
 
-    To configure the client to your liking please refer
-    http://python-consul.readthedocs.org/en/latest/. Few options like 'ttl'
-    and 'namespace' will be passed as part of the options. 'ttl' governs the
-    duration till when the session holding the lock will be active.
+    The Consul driver connection URI should look like::
+
+      consul://HOST[:PORT][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]]
+
+    If not specified, PORT defaults to 8500.
+    Available options are:
+
+    ==================  =======
+    Name                Default
+    ==================  =======
+    ttl                 15
+    namespace           tooz
+    ==================  =======
+
+    For details on the available options, refer to
+    http://python-consul.readthedocs.org/en/latest/.
 
     .. _python-consul: http://python-consul.readthedocs.org/
     .. _consul: https://consul.io/
diff --git a/tooz/drivers/etcd.py b/tooz/drivers/etcd.py
index 87c77fe..45bacca 100644
--- a/tooz/drivers/etcd.py
+++ b/tooz/drivers/etcd.py
@@ -203,6 +203,21 @@ class EtcdDriver(coordination.CoordinationDriver):
 
     This driver uses etcd provide the coordination driver semantics and
     required API(s).
+
+    The Etcd driver connection URI should look like::
+
+      etcd://[HOST[:PORT]][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]]
+
+    If not specified, HOST defaults to localhost and PORT defaults to 2379.
+    Available options are:
+
+    ==================  =======
+    Name                Default
+    ==================  =======
+    protocol            http
+    timeout             30
+    lock_timeout        30
+    ==================  =======
     """
 
     #: Default socket/lock/member/leader timeout used when none is provided.
diff --git a/tooz/drivers/etcd3.py b/tooz/drivers/etcd3.py
index 619f60a..be3015a 100644
--- a/tooz/drivers/etcd3.py
+++ b/tooz/drivers/etcd3.py
@@ -115,6 +115,22 @@ class Etcd3Driver(coordination.CoordinationDriverCachedRunWatchers,
 
     This driver uses etcd provide the coordination driver semantics and
     required API(s).
+
+    The Etcd driver connection URI should look like::
+
+      etcd3://[HOST[:PORT]][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]]
+
+    If not specified, HOST defaults to localhost and PORT defaults to 2379.
+    Available options are:
+
+    ==================  =======
+    Name                Default
+    ==================  =======
+    protocol            http
+    timeout             30
+    lock_timeout        30
+    membership_timeout  30
+    ==================  =======
     """
 
     #: Default socket/lock/member/leader timeout used when none is provided.
diff --git a/tooz/drivers/etcd3gw.py b/tooz/drivers/etcd3gw.py
index c229e6b..eedaf6f 100644
--- a/tooz/drivers/etcd3gw.py
+++ b/tooz/drivers/etcd3gw.py
@@ -166,6 +166,22 @@ class Etcd3Driver(coordination.CoordinationDriverWithExecutor):
 
     This driver uses etcd provide the coordination driver semantics and
     required API(s).
+
+    The Etcd driver connection URI should look like::
+
+      etcd3+http://[HOST[:PORT]][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]]
+
+    If not specified, HOST defaults to localhost and PORT defaults to 2379.
+    Available options are:
+
+    ==================  =======
+    Name                Default
+    ==================  =======
+    protocol            http
+    timeout             30
+    lock_timeout        30
+    membership_timeout  30
+    ==================  =======
     """
 
     #: Default socket/lock/member/leader timeout used when none is provided.
diff --git a/tooz/drivers/file.py b/tooz/drivers/file.py
index aaef57b..2ffa0a3 100644
--- a/tooz/drivers/file.py
+++ b/tooz/drivers/file.py
@@ -186,6 +186,13 @@ class FileDriver(coordination.CoordinationDriverCachedRunWatchers,
     missing some functionality but in the future these not implemented API(s)
     will be filled in.
 
+    The File driver connection URI should look like::
+
+      file://DIRECTORY[?timeout=TIMEOUT]
+
+    DIRECTORY is the location that should be used to store lock files.
+    TIMEOUT defaults to 10.
+
     General recommendations/usage considerations:
 
     - It does **not** automatically delete members from
diff --git a/tooz/drivers/ipc.py b/tooz/drivers/ipc.py
index f5d67a3..50885dc 100644
--- a/tooz/drivers/ipc.py
+++ b/tooz/drivers/ipc.py
@@ -141,6 +141,10 @@ class IPCDriver(coordination.CoordinationDriverWithExecutor):
     semantics and required API(s). It **is** missing some functionality but
     in the future these not implemented API(s) will be filled in.
 
+    The IPC driver connection URI should look like::
+
+      ipc://
+
     General recommendations/usage considerations:
 
     - It is **not** distributed (or recommended to be used in those
diff --git a/tooz/drivers/memcached.py b/tooz/drivers/memcached.py
index 3892e22..ad409d1 100644
--- a/tooz/drivers/memcached.py
+++ b/tooz/drivers/memcached.py
@@ -190,6 +190,23 @@ class MemcachedDriver(coordination.CoordinationDriverCachedRunWatchers,
     all of the coordination driver API(s). It stores data into memcache
     using expiries and `msgpack`_ encoded values.
 
+    The Memcached driver connection URI should look like::
+
+      memcached://[HOST[:PORT]][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]]
+
+    If not specified, HOST defaults to localhost and PORT defaults to 11211.
+    Available options are:
+
+    ==================  =======
+    Name                Default
+    ==================  =======
+    timeout             30
+    membership_timeout  30
+    lock_timeout        30
+    leader_timeout      30
+    max_pool_size       None
+    ==================  =======
+
     General recommendations/usage considerations:
 
     - Memcache (without different backend technology) is a **cache** enough
diff --git a/tooz/drivers/mysql.py b/tooz/drivers/mysql.py
index cbeea8d..269ec57 100644
--- a/tooz/drivers/mysql.py
+++ b/tooz/drivers/mysql.py
@@ -114,6 +114,12 @@ class MySQLDriver(coordination.CoordinationDriver):
     missing some functionality but in the future these not implemented API(s)
     will be filled in.
 
+    The MySQL driver connection URI should look like::
+
+      mysql://USERNAME:PASSWORD@HOST[:PORT]/DBNAME[?unix_socket=SOCKET_PATH]
+
+    If not specified, PORT defaults to 3306.
+
     .. _MySQL: http://dev.mysql.com/
     """
 
diff --git a/tooz/drivers/pgsql.py b/tooz/drivers/pgsql.py
index 1ad83df..6c60a20 100644
--- a/tooz/drivers/pgsql.py
+++ b/tooz/drivers/pgsql.py
@@ -174,6 +174,10 @@ class PostgresDriver(coordination.CoordinationDriver):
     missing some functionality but in the future these not implemented API(s)
     will be filled in.
 
+    The PostgreSQL driver connection URI should look like::
+
+      postgresql://[USERNAME[:PASSWORD]@]HOST:PORT?dbname=DBNAME
+
     .. _PostgreSQL: http://www.postgresql.org/
     """
 
diff --git a/tooz/drivers/redis.py b/tooz/drivers/redis.py
index d3cf4f6..5a5e771 100644
--- a/tooz/drivers/redis.py
+++ b/tooz/drivers/redis.py
@@ -138,6 +138,14 @@ class RedisDriver(coordination.CoordinationDriverCachedRunWatchers,
       some notion of HA (values *can* be lost when a failover transition
       occurs).
 
+    The Redis driver connection URI should look like::
+
+      redis://[:PASSWORD@]HOST:PORT[?OPTION=VALUE[&OPTION2=VALUE2[&...]]]
+
+    For a list of options recognized by this driver, see the documentation
+    for the member CLIENT_ARGS, and to determine the expected types of those
+    options see CLIENT_BOOL_ARGS, CLIENT_INT_ARGS, and CLIENT_LIST_ARGS.
+
     To use a `sentinel`_ the connection URI must point to the sentinel server.
     At connection time the sentinel will be asked for the current IP and port
     of the master and then connect there. The connection URI for sentinel
diff --git a/tooz/drivers/zookeeper.py b/tooz/drivers/zookeeper.py
index e033c05..db57f19 100644
--- a/tooz/drivers/zookeeper.py
+++ b/tooz/drivers/zookeeper.py
@@ -88,6 +88,10 @@ class KazooDriver(coordination.CoordinationDriverCachedRunWatchers):
     will be extracted from the coordinator url (or any provided options),
     so that a specific coordinator can be created that will work for you.
 
+    The Zookeeper coordinator url should look like::
+
+      zookeeper://[USERNAME:PASSWORD@][HOST[:PORT]][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]]
+
     Currently the following options will be proxied to the contained client:
 
     ================  ===============================  ====================