openstack
/
tooz
Code Issues Proposed changes

Merge "More explicitly document driver connection strings"

This commit is contained in:
Zuul 2019-02-13 12:14:37 +00:00 committed by Gerrit Code Review
parent 17b9e9d42c e76235b675
commit d55449258a
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:
================ =============================== ====================