addressing review comments

Matt Howlett · Matt Howlett · commit e7da3caae223 · 2018-04-10T19:03:22.000-07:00
diff --git a/examples/confluent_cloud.py b/examples/confluent_cloud.py
@@ -20,82 +20,94 @@
 #
 # https://www.confluent.io/confluent-cloud/
 #
-# Confluent Cloud does not auto-create topics. You will need to use the ccloud
-# cli to create the python-test-topic topic before running this example. The
-# <ccloud bootstrap servers>, <ccloud key> and <ccloud secret> parameters are
-# available via the confluent cloud web interface. For more information,
+# Auto-creation of topics is disabled in Confluent Cloud. You will need to
+# use the ccloud cli to create the python-test-topic topic before running this
+# example.
+#
+# $ ccloud topic create python-test-topic
+#
+# The <ccloud bootstrap servers>, <ccloud key> and <ccloud secret> parameters
+# are available via the Confluent Cloud web interface. For more information,
 # refer to the quick-start:
 #
 # https://docs.confluent.io/current/cloud-quickstart.html
 #
-# to execute using Python 2.x:
-#   virtualenv ccloud_example
-#   source ccloud_example/bin/activate
-#   pip install confluent_kafka
-#   python example.py
-#   deactivate
+# to execute using Python 2.7:
+# $ virtualenv ccloud_example
+# $ source ccloud_example/bin/activate
+# $ pip install confluent_kafka
+# $ python confluent_cloud.py
+# $ deactivate
 #
-# to execute using Python 3.x: 
-#   python -m venv ccloud_example
-#   source ccloud_example/bin/activate
-#   pip install confluent_kafka
-#   python example.py
-#   deactivate
+# to execute using Python 3.x:
+# $ python -m venv ccloud_example
+# $ source ccloud_example/bin/activate
+# $ pip install confluent_kafka
+# $ python confluent_cloud.py
+# $ deactivate
 
 import uuid
 from confluent_kafka import Producer, Consumer, KafkaError
 
 p = Producer({
-    'bootstrap.servers': '<bootstrap servers>',
-    'api.version.request': True,
+    'bootstrap.servers': '<ccloud bootstrap servers>',
     'broker.version.fallback': '0.10.0.0',
     'api.version.fallback.ms': 0,
     'sasl.mechanisms': 'PLAIN',
     'security.protocol': 'SASL_SSL',
-    'ssl.ca.location': '/usr/local/etc/openssl/cert.pem',
-    'sasl.username': '<key>',
-    'sasl.password': '<secret>'
+    'sasl.username': '<ccloud key>',
+    'sasl.password': '<ccloud secret>'
 })
 
+
 def acked(err, msg):
+    """Delivery report callback called (from flush()) on successful or failed delivery of the message."""
     if err is not None:
         print("failed to deliver message: {0}".format(err.str()))
     else:
-        print("produced to: {0}/{1}/{2}".format(msg.topic(), msg.partition(), msg.offset()))
+        print("produced to: {0} [{1}] @ {2}".format(msg.topic(), msg.partition(), msg.offset()))
+
 
 p.produce('python-test-topic', value='python test value', callback=acked)
+
+# flush() is typically called when the producer is done sending messages to wait
+# for outstanding messages to be transmitted to the broker and delivery report
+# callbacks to get called. For continous producing you should call p.poll(0)
+# after each produce() call to trigger delivery report callbacks.
 p.flush(10)
 
 c = Consumer({
-    'bootstrap.servers': '<bootstrap servers>',
-    'api.version.request': True,
+    'bootstrap.servers': '<ccloud bootstrap servers>',
     'broker.version.fallback': '0.10.0.0',
     'api.version.fallback.ms': 0,
     'sasl.mechanisms': 'PLAIN',
     'security.protocol': 'SASL_SSL',
-    'ssl.ca.location': '/usr/local/etc/openssl/cert.pem',
-    'sasl.username': '<key>',
-    'sasl.password': '<secret>',
-    'group.id': str(uuid.uuid1()),
+    'sasl.username': '<ccloud key>',
+    'sasl.password': '<ccloud secret>',
+    'group.id': str(uuid.uuid1()),  # this will create a new consumer group on each invocation.
     'default.topic.config': {'auto.offset.reset': 'smallest'}
 })
 
 c.subscribe(['python-test-topic'])
 
 try:
     while True:
-        msg = c.poll(0.1)
+        msg = c.poll(0.1)  # Wait for message or event/error
         if msg is None:
+            # No message available within timeout.
+            # Initial message consumption may take up to `session.timeout.ms` for
+            #   the group to rebalance and start consuming
             continue
         elif not msg.error():
             print('consumed: {0}'.format(msg.value()))
         elif msg.error().code() == KafkaError._PARTITION_EOF:
-            print('end of partition: {0}/{1}'.format(msg.topic(), msg.partition()))
+            print('end of partition: {0} [{1}] @ {2}'.format(msg.topic(), msg.partition(), msg.offset()))
         else:
             print('error: {0}'.format(msg.error().str()))
 
 except KeyboardInterrupt:
     pass
 
 finally:
+    # Leave group and commit final offsets
     c.close()
