Merge "More explicitly document driver connection strings"

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

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
 ~~~~
 

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

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
+    The Consul driver connection URI should look like::
-    http://python-consul.readthedocs.org/en/latest/. Few options like 'ttl'
+
-    and 'namespace' will be passed as part of the options. 'ttl' governs the
+      consul://HOST[:PORT][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]]
-    duration till when the session holding the lock will be active.
+
+    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/

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.

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.

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.

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

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

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

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/
     """
 

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/
     """
 

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

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