Add ClusterMetadata documentation

Author: dpkp

docs/apidoc/ClusterMetadata.rst

@@ -0,0 +1,5 @@
+ClusterMetadata
+===========
+
+.. autoclass:: kafka.cluster.ClusterMetadata
+    :members:

docs/apidoc/kafka.rst

@@ -6,13 +6,23 @@ Subpackages
 
 .. toctree::
 
+    kafka.cluster
     kafka.consumer
     kafka.partitioner
     kafka.producer
 
 Submodules
 ----------
 
+kafka.cluster module
+--------------------
+
+.. automodule:: kafka.cluster
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
 kafka.client module
 -------------------
 

docs/apidoc/modules.rst

@@ -7,3 +7,4 @@ kafka-python API
    KafkaProducer
    KafkaClient
    BrokerConnection
+   ClusterMetadata

kafka/client_async.py

@@ -48,6 +48,10 @@ class KafkaClient(object):
 
     This class is not thread-safe!
 
+    Attributes:
+        cluster (:any:`ClusterMetadata`): Local cache of cluster metadata, retrived
+            via MetadataRequests during :meth:`.poll`.
+
     Keyword Arguments:
         bootstrap_servers: 'host[:port]' string (or list of 'host[:port]'
             strings) that the consumer should contact to bootstrap initial

kafka/cluster.py

@@ -16,6 +16,20 @@
 
 
 class ClusterMetadata(object):
+    """
+    A class to manage kafka cluster metadata.
+
+    This class does not perform any IO. It simply updates internal state
+    given API responses (MetadataResponse, GroupCoordinatorResponse).
+
+    Keyword Arguments:
+        retry_backoff_ms (int): Milliseconds to backoff when retrying on
+            errors. Default: 100.
+        metadata_max_age_ms (int): The period of time in milliseconds after
+            which we force a refresh of metadata even if we haven't seen any
+            partition leadership changes to proactively discover any new
+            brokers or partitions. Default: 300000
+    """
     DEFAULT_CONFIG = {
         'retry_backoff_ms': 100,
         'metadata_max_age_ms': 300000,