From c5d8ef9067fd8232e4c7a78ba624a93addaf1125 Mon Sep 17 00:00:00 2001 From: Joshua Harlow Date: Fri, 10 Jul 2015 16:10:34 -0700 Subject: [PATCH] Update 'make_client' kazoo docs and link to them Since the creation of a client is somewhat important and knowing what the options that are transfereed to kazoo are we should explicitly document what keys are and what the values should be. Change-Id: I1a5037b274828190270ea5c402be8b2100306de4 --- taskflow/jobs/backends/impl_zookeeper.py | 10 +++++ .../persistence/backends/impl_zookeeper.py | 10 +++++ taskflow/utils/kazoo_utils.py | 38 ++++++++++++++++++- 3 files changed, 57 insertions(+), 1 deletion(-) diff --git a/taskflow/jobs/backends/impl_zookeeper.py b/taskflow/jobs/backends/impl_zookeeper.py index b6f85465..15b54b13 100644 --- a/taskflow/jobs/backends/impl_zookeeper.py +++ b/taskflow/jobs/backends/impl_zookeeper.py @@ -213,6 +213,16 @@ class ZookeeperJobBoard(base.NotifyingJobBoard): zookeeper when the ephemeral node and associated session is deemed to have been lost). + Do note that the creation of a kazoo client is achieved + by :py:func:`~taskflow.utils.kazoo_utils.make_client` and the transfer + of this jobboard configuration to that function to make a + client may happen at ``__init__`` time. This implies that certain + parameters from this jobboard configuration may be provided to + :py:func:`~taskflow.utils.kazoo_utils.make_client` such + that if a client was not provided by the caller one will be created + according to :py:func:`~taskflow.utils.kazoo_utils.make_client`'s + specification + .. _zookeeper: http://zookeeper.apache.org/ .. _json: http://json.org/ """ diff --git a/taskflow/persistence/backends/impl_zookeeper.py b/taskflow/persistence/backends/impl_zookeeper.py index 687f103d..11897233 100644 --- a/taskflow/persistence/backends/impl_zookeeper.py +++ b/taskflow/persistence/backends/impl_zookeeper.py @@ -39,6 +39,16 @@ class ZkBackend(path_based.PathBasedBackend): "hosts": "192.168.0.1:2181,192.168.0.2:2181,192.168.0.3:2181", "path": "/taskflow", } + + Do note that the creation of a kazoo client is achieved + by :py:func:`~taskflow.utils.kazoo_utils.make_client` and the transfer + of this backend configuration to that function to make a + client may happen at ``__init__`` time. This implies that certain + parameters from this backend configuration may be provided to + :py:func:`~taskflow.utils.kazoo_utils.make_client` such + that if a client was not provided by the caller one will be created + according to :py:func:`~taskflow.utils.kazoo_utils.make_client`'s + specification """ #: Default path used when none is provided. diff --git a/taskflow/utils/kazoo_utils.py b/taskflow/utils/kazoo_utils.py index 4baa317c..4ca0ebaa 100644 --- a/taskflow/utils/kazoo_utils.py +++ b/taskflow/utils/kazoo_utils.py @@ -145,7 +145,43 @@ def check_compatible(client, min_version=None, max_version=None): def make_client(conf): - """Creates a kazoo client given a configuration dictionary.""" + """Creates a `kazoo`_ `client`_ given a configuration dictionary. + + :param conf: configuration dictionary that will be used to configure + the created client + :type conf: dict + + The keys that will be extracted are: + + - ``read_only``: boolean that specifies whether to allow connections to + read only servers, defaults to ``False`` + - ``randomize_hosts``: boolean that specifies whether to randomize + host lists provided, defaults to ``False`` + - ``command_retry``: a kazoo `retry`_ object (or dict of options which + will be used for creating one) that will be used for retrying commands + that are executed + - ``connection_retry``: a kazoo `retry`_ object (or dict of options which + will be used for creating one) that will be used for retrying + connection failures that occur + - ``hosts``: a string, list, set (or dict with host keys) that will + specify the hosts the kazoo client should be connected to, if none + is provided then ``localhost:2181`` will be used by default + - ``timeout``: a float value that specifies the default timeout that the + kazoo client will use + - ``handler``: a kazoo handler object that can be used to provide the + client with alternate async strategies (the default is `thread`_ + based, but `gevent`_, or `eventlet`_ ones can be provided as needed) + + .. _client: http://kazoo.readthedocs.org/en/latest/api/client.html + .. _kazoo: kazoo.readthedocs.org/ + .. _retry: http://kazoo.readthedocs.org/en/latest/api/retry.html + .. _gevent: http://kazoo.readthedocs.org/en/latest/api/\ + handlers/gevent.html + .. _eventlet: http://kazoo.readthedocs.org/en/latest/api/\ + handlers/eventlet.html + .. _thread: http://kazoo.readthedocs.org/en/latest/api/\ + handlers/threading.html + """ # See: http://kazoo.readthedocs.org/en/latest/api/client.html client_kwargs = { 'read_only': bool(conf.get('read_only')),