Merge "Update 'make_client' kazoo docs and link to them"

3 files changed, 57 insertions, 1 deletions

diff --git a/taskflow/jobs/backends/impl_zookeeper.py b/taskflow/jobs/backends/impl_zookeeper.py
index 34a87d5..91e4c3f 100644
--- a/taskflow/jobs/backends/impl_zookeeper.py
+++ b/taskflow/jobs/backends/impl_zookeeper.py
@@ -273,6 +273,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 687f103..1189723 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 f681dc4..c60a9a8 100644
--- a/taskflow/utils/kazoo_utils.py
+++ b/taskflow/utils/kazoo_utils.py
@@ -151,7 +151,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')),