Update docs for api_version_auto_timeout_ms (#1812)

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.

1 files changed, 20 insertions, 2 deletions

diff --git a/test/testutil.py b/test/testutil.py
index a8227cf..b7b4513 100644
--- a/test/testutil.py
+++ b/test/testutil.py
@@ -16,10 +16,28 @@ from kafka.errors import (
     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 kafka_versions(*versions):
             '<=': 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)