Improve KafkaProducer docstring re retries config

dpkp · dpkp · commit 754ff8954e2a · 2016-08-20T17:41:45.000-07:00
diff --git a/kafka/producer/kafka.py b/kafka/producer/kafka.py
@@ -121,10 +121,12 @@ class KafkaProducer(object):
         retries (int): Setting a value greater than zero will cause the client
             to resend any record whose send fails with a potentially transient
             error. Note that this retry is no different than if the client
-            resent the record upon receiving the error. Allowing retries will
-            potentially change the ordering of records because if two records
+            resent the record upon receiving the error. Allowing retries
+            without setting max_in_flight_connections_per_connection to 1 will
+            potentially change the ordering of records because if two batches
             are sent to a single partition, and the first fails and is retried
-            but the second succeeds, then the second record may appear first.
+            but the second succeeds, then the records in the second batch may
+            appear first.
             Default: 0.
         batch_size (int): Requests sent to brokers will contain multiple
             batches, one for each partition with data available to be sent.
