Update docs for api_version_auto_timeout_ms (dpkp#1812)

jeffwidman · jeffwidman · commit cee4d17df785 · 2019-05-24T00:15:58.000-07:00
The docs for `api_version_auto_timeout_ms` mention setting
`api_version='auto'` but that value has been deprecated for years in
favor of `api_version=None`.

Updating the docs for now, and will remove support for `'auto'` in next
major version bump.
diff --git a/kafka/consumer/group.py b/kafka/consumer/group.py
@@ -209,7 +209,7 @@ class KafkaConsumer(six.Iterator):
             Default: None
         api_version_auto_timeout_ms (int): number of milliseconds to throw a
             timeout exception from the constructor when checking the broker
-            api version. Only applies if api_version set to 'auto'
+            api version. Only applies if api_version set to None.
         connections_max_idle_ms: Close idle connections after the number of
             milliseconds specified by this config. The broker closes idle
             connections after connections.max.idle.ms, so this avoids hitting
diff --git a/kafka/producer/kafka.py b/kafka/producer/kafka.py
@@ -255,7 +255,7 @@ class KafkaProducer(object):
             various APIs. Example: (0, 10, 2). Default: None
         api_version_auto_timeout_ms (int): number of milliseconds to throw a
             timeout exception from the constructor when checking the broker
-            api version. Only applies if api_version set to 'auto'
+            api version. Only applies if api_version set to None.
         metric_reporters (list): A list of classes to use as metrics reporters.
             Implementing the AbstractMetricsReporter interface allows plugging
             in classes that will be notified of new metric creation. Default: []
diff --git a/test/fixtures.py b/test/fixtures.py
@@ -26,13 +26,17 @@
 def random_string(length):
     return "".join(random.choice(string.ascii_letters) for i in range(length))
 
-def version_str_to_list(version_str):
-    return tuple(map(int, version_str.split('.'))) # e.g., (0, 8, 1, 1)
+def version_str_to_tuple(version_str):
+    """Transform a version string into a tuple.
+
+    Example: '0.8.1.1' --> (0, 8, 1, 1)
+    """
+    return tuple(map(int, version_str.split('.')))
 
 def version():
     if 'KAFKA_VERSION' not in os.environ:
         return ()
-    return version_str_to_list(os.environ['KAFKA_VERSION'])
+    return version_str_to_tuple(os.environ['KAFKA_VERSION'])
 
 def get_open_port():
     sock = socket.socket()
diff --git a/test/testutil.py b/test/testutil.py
@@ -16,10 +16,28 @@
     FailedPayloadsError
 )
 from kafka.structs import OffsetRequestPayload
-from test.fixtures import random_string, version_str_to_list, version as kafka_version #pylint: disable=wrong-import-order
+from test.fixtures import random_string, version_str_to_tuple, version as kafka_version #pylint: disable=wrong-import-order
 
 
 def kafka_versions(*versions):
+    """
+    Describe the Kafka versions this test is relevant to.
+
+    The versions are passed in as strings, for example:
+        '0.11.0'
+        '>=0.10.1.0'
+        '>0.9', '<1.0'  # since this accepts multiple versions args
+
+    The current KAFKA_VERSION will be evaluated against this version. If the
+    result is False, then the test is skipped. Similarly, if KAFKA_VERSION is
+    not set the test is skipped.
+
+    Note: For simplicity, this decorator accepts Kafka versions as strings even
+    though the similarly functioning `api_version` only accepts tuples. Trying
+    to convert it to tuples quickly gets ugly due to mixing operator strings
+    alongside version tuples. While doable when one version is passed in, it
+    isn't pretty when multiple versions are passed in.
+    """
 
     def construct_lambda(s):
         if s[0].isdigit():
@@ -43,7 +61,7 @@ def construct_lambda(s):
             '<=': operator.le
         }
         op = op_map[op_str]
-        version = version_str_to_list(v_str)
+        version = version_str_to_tuple(v_str)
         return lambda a: op(a, version)
 
     validators = map(construct_lambda, versions)
