Merge tag 'v0.9.1.2' into 3.0.x

ewencp · ewencp · commit ef3e2bc763c9 · 2016-08-04T12:30:57.000-07:00
diff --git a/README.md b/README.md
@@ -1,57 +1,108 @@
 Confluent's Apache Kafka client for Python
 ==========================================
 
+Confluent's Kafka client for Python wraps the librdkafka C library, providing
+full Kafka protocol support with great performance and reliability.
 
-Prerequisites
-===============
+The Python bindings provides a high-level Producer and Consumer with support
+for the balanced consumer groups of Apache Kafka 0.9.
 
-    librdkafka >=0.9.1 (or master>=2016-04-13)
-    py.test  (pip install pytest)
+See the [API documentation](http://docs.confluent.io/current/clients/confluent-kafka-python/index.html) for more info.
 
+**License**: [Apache License v2.0](http://www.apache.org/licenses/LICENSE-2.0)
 
-Build
+
+Usage
 =====
 
-    python setup.py build
+**Producer:**
+
+```python
+from confluent_kafka import Producer
+
+p = Producer({'bootstrap.servers': 'mybroker,mybroker2'})
+for data in some_data_source:
+    p.produce('mytopic', data.encode('utf-8'))
+p.flush()
+```
+
+
+**High-level Consumer:**
+
+```python
+from confluent_kafka import Consumer
+
+c = Consumer({'bootstrap.servers': 'mybroker', 'group.id': 'mygroup',
+              'default.topic.config': {'auto.offset.reset': 'smallest'}})
+c.subscribe(['mytopic'])
+while running:
+    msg = c.poll()
+    if not msg.error():
+        print('Received message: %s' % msg.value().decode('utf-8'))
+c.close()
+```
 
+See [examples](examples) for more examples.
+
+
+Prerequisites
+=============
+
+ * Python >= 2.7 or Python 3.x
+ * [librdkafka](https://github.com/edenhill/librdkafka) >= 0.9.1
 
 
 Install
 =======
-Preferably in a virtualenv:
 
-    pip install .
+**Install from PyPi:**
+
+    $ pip install confluent-kafka
+
+
+**Install from source / tarball:**
+
+    $ pip install .
 
 
-Run unit-tests
-==============
+Build
+=====
+
+    $ python setup.by build
+
+If librdkafka is installed in a non-standard location provide the include and library directories with:
+
+    $ CPLUS_INCLUDE_PATH=/path/to/include LIBRARY_PATH=/path/to/lib python setup.py ...
+
+
+Tests
+=====
+
 
-    py.test
+**Run unit-tests:**
 
+    $ py.test
+
+**NOTE**: Requires `py.test`, install by `pip install pytest`
+
+
+**Run integration tests:**
+
+    $ examples/integration_test.py <kafka-broker>
 
-Run integration tests
-=====================
 **WARNING**: These tests require an active Kafka cluster and will make use of a topic named 'test'.
 
-    examples/integration_test.py <kafka-broker>
 
 
 
 Generate documentation
 ======================
 Install sphinx and sphinx_rtd_theme packages and then:
 
-    make docs
+    $ make docs
 
 or:
 
-    python setup.py build_sphinx
-
-
-Documentation will be generated in `docs/_build/`
-
-
-Examples
-========
+    $ python setup.by build_sphinx
 
-See [examples](examples)
+Documentation will be generated in `docs/_build/`.
diff --git a/confluent_kafka/src/Producer.c b/confluent_kafka/src/Producer.c
@@ -370,8 +370,8 @@ static PyMethodDef Producer_methods[] = {
 	  "message has been succesfully delivered or permanently fails delivery.\n"
 	  "\n"
 	  "  :param str topic: Topic to produce message to\n"
-	  "  :param str value: Message payload\n"
-	  "  :param str key: Message key\n"
+	  "  :param str|bytes value: Message payload\n"
+	  "  :param str|bytes key: Message key\n"
 	  "  :param int partition: Partition to produce to, elses uses the "
 	  "configured partitioner.\n"
 	  "  :param func on_delivery(err,msg): Delivery report callback to call "
diff --git a/confluent_kafka/src/confluent_kafka.c b/confluent_kafka/src/confluent_kafka.c
@@ -339,12 +339,12 @@ static PyMethodDef Message_methods[] = {
 
 	{ "value", (PyCFunction)Message_value, METH_NOARGS,
 	  "  :returns: message value (payload) or None if not available.\n"
-	  "  :rtype: str or None\n"
+	  "  :rtype: str|bytes or None\n"
 	  "\n"
 	},
 	{ "key", (PyCFunction)Message_key, METH_NOARGS,
 	  "  :returns: message key or None if not available.\n"
-	  "  :rtype: str or None\n"
+	  "  :rtype: str|bytes or None\n"
 	  "\n"
 	},
 	{ "topic", (PyCFunction)Message_topic, METH_NOARGS,
@@ -486,10 +486,10 @@ PyObject *Message_new0 (const rd_kafka_message_t *rkm) {
 		self->topic = cfl_PyUnistr(
 			_FromString(rd_kafka_topic_name(rkm->rkt)));
 	if (rkm->payload)
-		self->value = cfl_PyUnistr(_FromStringAndSize(rkm->payload,
-							       rkm->len));
+		self->value = cfl_PyBin(_FromStringAndSize(rkm->payload,
+							   rkm->len));
 	if (rkm->key)
-		self->key = cfl_PyUnistr(
+		self->key = cfl_PyBin(
 			_FromStringAndSize(rkm->key, rkm->key_len));
 
 	self->partition = rkm->partition;
diff --git a/confluent_kafka/src/confluent_kafka.h b/confluent_kafka/src/confluent_kafka.h
@@ -41,12 +41,12 @@
  *
  ****************************************************************************/
 
-#ifdef PY3
+#ifdef PY3 /* Python 3 */
 /**
  * @brief Binary type, use as cfl_PyBin(_X(A,B)) where _X() is the type-less
- *        suffix of a PyBinary/Str_X() function
+ *        suffix of a PyBytes/Str_X() function
 */
-#define cfl_PyBin(X)    PyBinary ## X
+#define cfl_PyBin(X)    PyBytes ## X
 
 /**
  * @brief Unicode type, same usage as PyBin()
@@ -62,7 +62,8 @@
  * @returns Unicode Python string object
  */
 #define cfl_PyObject_Unistr(X)  PyObject_Str(X)
-#else
+
+#else /* Python 2 */
 
 /* See comments above */
 #define cfl_PyBin(X)    PyString ## X
diff --git a/docs/conf.py b/docs/conf.py
@@ -55,9 +55,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.9.1'
+version = '0.9.1.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.9.1'
+release = '0.9.1.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/setup.py b/setup.py
@@ -5,14 +5,13 @@
 
 
 module = Extension('confluent_kafka.cimpl',
-                    include_dirs = ['/usr/local/include'],
                     libraries= ['rdkafka'],
                     sources=['confluent_kafka/src/confluent_kafka.c',
                              'confluent_kafka/src/Producer.c',
                              'confluent_kafka/src/Consumer.c'])
 
 setup(name='confluent-kafka',
-      version='0.9.1.1',
+      version='0.9.1.2',
       description='Confluent\'s Apache Kafka client for Python',
       author='Confluent Inc',
       author_email='support@confluent.io',
