openstack/tooz
Code Issues Proposed changes

More explicitly document driver connection strings

Browse Source 
If you're not intimately familiar with RFC 1808 it can be a bit tricky to
write tooz connection strings. In addition, some drivers do not document the
options that they recognize in a connection string. This can force a user to
read the driver code in order to figure out how to configure tooz to use said
driver, which should not be the case.

This change more explicitly documents the format of the connection string,
including which parts of an RFC 1808 URI it recognizes, and the options that
can be passed. It also clarifies which parts of the connection string are
optional (possibly because they have defaults) and which must always be
included.

Note that not every possible configuration is documented. For example, the
postgres driver supports multiple methods of configuring the connection host
and port. For consistency, I only documented the one that matches the other
drivers. This should be sufficient to allow a user to write a working
connection string.

This change also wires the etcd3 and etcd3gw drivers into the doc index since
they were missing before.

Change-Id: I66e54433115f27fb54badc2173f8f6044c49aacb
This commit is contained in:
Ben Nemec 2018-12-10 23:43:28 +00:00
parent 70f144abde
commit e76235b675
14 changed files with 160 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/requirements.txt
View File

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

12
doc/source/reference/index.rst
View File

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

33
doc/source/user/drivers.rst
View File

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

20
tooz/drivers/consul.py
View File

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

15
tooz/drivers/etcd.py
View File

@ -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.

16
tooz/drivers/etcd3.py
View File

@ -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.

16
tooz/drivers/etcd3gw.py
View File

@ -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.

7
tooz/drivers/file.py
View File

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

4
tooz/drivers/ipc.py
View File

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

17
tooz/drivers/memcached.py
View File

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

6
tooz/drivers/mysql.py
View File

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

4
tooz/drivers/pgsql.py
View File

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

8
tooz/drivers/redis.py
View File

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

4
tooz/drivers/zookeeper.py
View File

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