Make derived producer/consumer non-instantiable

rnpridgeon · rnpridgeon · commit 7333f2a0e756 · 2018-12-30T13:07:01.000-05:00
diff --git a/confluent_kafka/consumer.py b/confluent_kafka/consumer.py
@@ -21,9 +21,17 @@
 from warnings import warn
 
 
+def byteDeserializer(topic, payload):
+    """
+        byteDeserializer returns an unaltered payload to the caller
+    """
+
+    return payload
+
+
 class Consumer(_impl):
     """
-        Create a new Kafka Consumer instance with or without serializer support.
+        Create a new Kafka Consumer instance.
 
         To avoid spontaneous calls from non-Python threads all callbacks will only be served upon
         calling ```client.poll()``` or ```client.flush()```.
@@ -51,31 +59,24 @@ def __new__(cls, *args, **kwargs):
 
 class DeserializingConsumer(Consumer):
     """
-        Create a new Kafka Consumer instance.
+        DeserializingConsumer extends Consumer with configurable key and value deserializer.
 
-        To avoid spontaneous calls from non-Python threads all callbacks will only be served upon
-        calling ```client.poll()``` or ```client.flush()```.
+        Instances of DeserializingConsumer cannot be created directly.
+        To obtain an instance of this class instantiate a Consumer with a key and/or value deserializer.
+
+        Duplicate params have been omitted for brevity. See Consumer for class documentation.
 
-        :param dict conf: Configuration properties.
-            See https://github.com/edenhill/librdkafka/blob/master/CONFIGURATION.md for more information.
-        :param func key_deserializer(topic, key): Converts message key bytes to object.
-            **note** deserializers are responsible for handling NULL keys
-        :param func value_deserializer(topic, value): Converts message value bytes to object.
-            **note** deserializers are responsible for handling NULL values
-        :param func on_commit(err, [partitions]): Callback used to indicate success or failure
-            of an offset commit.
-        :param func stats_cb(json_str): Callback for statistics emitted every ``statistics.interval.ms``.
-            See https://github.com/edenhill/librdkafka/wiki/Statistics” for more information.
-        :param func throttle_cb(confluent_kafka.ThrottleEvent): Callback for throttled request reporting.
-        :param logging.handlers logger: Forwards logs from the Kafka client to the provided handler instance.
-            Log messages will only be forwarded when ``client.poll()`` or ``producer.flush()`` are called.
         :raises TypeError: If conf is not a dict.
+        :raises TypeError: If instantiated directly.
     """
 
     __slots__ = ["_key_deserializer", "_value_deserializer"]
 
+    def __new__(cls, *args, **kwargs):
+        raise TypeError("DeserializingConsumer is a non user-instantiable class")
+
     # conf must remain optional as long as kwargs are supported
-    def __init__(self, conf={}, key_deserializer=None, value_deserializer=None,
+    def __init__(self, conf={}, key_deserializer=byteDeserializer, value_deserializer=byteDeserializer,
                  on_commit=None, stats_cb=None, throttle_cb=None, logger=None, **kwargs):
 
         if not isinstance(conf, dict):
@@ -143,15 +144,14 @@ def consume(self, num_messages=1, timeout=-1):
             Consume messages, calls callbacks and returns a list of messages. (possibly empty on timeout)
 
             The application must check Message.error() to distinguish between
-                proper messages, an error(see error().code() for specifics), or an event. for each
+                proper messages, an error(see error().code() for specifics), or an event for each
                 Message in the list.
 
             :param int num_messages: Maximum number of messages to return (default: 1)
             :param float timeout: Maximum time in seconds to block waiting for message, event or callback.
                 (default: infinite (-1))
             :returns: A list of Message objects (possibly empty on timeout)
             :rtype: list(Message)
-            :raises NotImplementedError: If used with key/value serializers.
             :raises RuntimeError: If called on a closed consumer.
             :raises KafkaError: In case of internal error.
             :raises ValueError: If num_messages > 1M.
@@ -162,7 +162,7 @@ def consume(self, num_messages=1, timeout=-1):
             if msg.error():
                 continue
 
-            msg.set_key(self._key_deserializer(topic, msg.key()))
-            msg.set_value(self._value_deserializer(topic, msg.value()))
+            msg.set_key(self._key_deserializer(msg.topic(), msg.key()))
+            msg.set_value(self._value_deserializer(msg.topic(), msg.value()))
 
         return msgset
diff --git a/confluent_kafka/producer.py b/confluent_kafka/producer.py
@@ -21,6 +21,14 @@
 from warnings import warn
 
 
+def byteSerializer(topic, payload):
+    """
+        byteSerializer returns an unaltered payload to the caller
+    """
+
+    return payload
+
+
 class Producer(_impl):
     """
         Create a new Kafka Producer instance with or without serializer support.
@@ -51,30 +59,27 @@ def __new__(cls, *args, **kwargs):
 
 class SerializingProducer(Producer):
     """
-        Create a new Kafka Producer instance with custom serialization support.
+        SerializingProducer extends Producer with configurable key and value serializer.
 
         To avoid spontaneous calls from non-Python threads all callbacks will only be served upon
             calling ```client.poll()``` or ```client.flush()```.
 
-        :param dict conf: Configuration properties. At a minimum ``bootstrap.servers`` **should** be set.
-            See https://github.com/edenhill/librdkafka/blob/master/CONFIGURATION.md for more information.
-        :param func key_serializer(topic, key): Converts key to bytes.
-            **note** serializers are responsible for handling NULL keys
-        :param func value_serializer(topic, value): Converts value to bytes.
-            **note** serializers are responsible for handling NULL keys
-        :param func error_cb(kafka.KafkaError): Callback for generic/global error events.
-        :param func stats_cb(json_str): Callback for statistics emitted every ``statistics.interval.ms``.
-            See https://github.com/edenhill/librdkafka/wiki/Statistics” for more information.
-        :param func throttle_cb(confluent_kafka.ThrottleEvent): Callback for throttled request reporting.
-        :param logging.handlers logger: Forwards logs from the Kafka client to the provided handler instance.
-            Log messages will only be forwarded when ``client.poll()`` or ``producer.flush()`` are called.
-        :raises TypeError: If conf is not a dict object.
+        Instances of SerializingProducer cannot be created directly.
+        To obtain an instance of this class instantiate a Consumer with a key and/or value deserializer.
+
+        Duplicate params have been omitted for brevity. See Consumer for class documentation.
+
+        :raises TypeError: If conf is not a dict.
+        :raises TypeError: If instantiated directly.
     """
 
     __slots__ = ["_key_serializer", "_value_serializer"]
 
+    def __new__(cls, *args, **kwargs):
+        raise TypeError("SerializingProducer is a non user-instantiable class")
+
     # conf must remain optional as long as kwargs are supported
-    def __init__(self, conf={}, key_serializer=None, value_serializer=None,
+    def __init__(self, conf={}, key_serializer=byteSerializer, value_serializer=byteSerializer,
                  error_cb=None, stats_cb=None, throttle_cb=None, logger=None, **kwargs):
 
         if not isinstance(conf, dict):
diff --git a/tests/test_Consumer.py b/tests/test_Consumer.py
@@ -338,3 +338,12 @@ def test_producer_factory(test_param):
 
     c = Consumer({'group.id': 'wrapper'}, **test_param[0])
     assert(type(c) is test_param[1])
+
+
+def test_deserializing_consumer_instantiation():
+    """
+    Assert DeserializingConsumer instances cannot be created directly
+    """
+    with pytest.raises(TypeError) as e:
+        DeserializingConsumer()
+    assert 'DeserializingConsumer is a non user-instantiable class' in str(e)
diff --git a/tests/test_Producer.py b/tests/test_Producer.py
@@ -208,3 +208,12 @@ def test_producer_factory(test_param):
 
     p = Producer(**test_param[0])
     assert(type(p) is test_param[1])
+
+
+def test_serializing_producer_instantiation():
+    """
+    Assert SerializingProducer instances cannot be created directly
+    """
+    with pytest.raises(TypeError) as e:
+        SerializingProducer()
+    assert 'SerializingProducer is a non user-instantiable class' in str(e)
