docstrings, marshallers

Signed-off-by: Denis Makogon <[email protected]>

Author: denismakogon

cloudevents/sdk/converters/base.py

@@ -30,10 +30,8 @@ def __init__(
     def can_read(self, media_type: str) -> bool:
         return media_type in self.supported_media_types
 
-    def can_write(self, media_type: str) -> bool:
-        return media_type in self.supported_media_types
-
-    def read(self, headers: dict, body: typing.IO) -> base.BaseEvent:
+    def read(self, headers: dict, body: typing.IO,
+             data_unmarshaller: typing.Callable) -> base.BaseEvent:
         raise Exception("not implemented")
 
     def write(self, event: base.BaseEvent,

cloudevents/sdk/converters/binary.py

@@ -32,14 +32,18 @@ def __init__(self, event_class: event_base.BaseEvent,
         super().__init__(event_class, supported_media_types)
 
     def read(self,
-             headers: dict, body: typing.IO) -> event_base.BaseEvent:
+             headers: dict, body: typing.IO,
+             data_unmarshaller: typing.Callable) -> event_base.BaseEvent:
         # we ignore headers, since the whole CE is in request body
         event = self.event
-        event.UnmarshalBinary(headers, body)
+        event.UnmarshalBinary(headers, body, data_unmarshaller)
         return event
 
     def write(self, event: event_base.BaseEvent,
               data_marshaller: typing.Callable) -> (dict, typing.IO):
+        if not isinstance(data_marshaller, typing.Callable):
+            raise exceptions.InvalidDataMarshaller()
+
         hs, data = event.MarshalBinary()
         return hs, data_marshaller(data)
 

cloudevents/sdk/converters/structured.py

@@ -14,6 +14,7 @@
 
 import typing
 
+from cloudevents.sdk import exceptions
 from cloudevents.sdk.converters import base
 from cloudevents.sdk.event import base as event_base
 
@@ -27,16 +28,20 @@ def __init__(self, event_class: event_base.BaseEvent,
         super().__init__(event_class, supported_media_types)
 
     def read(self, headers: dict,
-             body: typing.IO) -> event_base.BaseEvent:
+             body: typing.IO,
+             data_unmarshaller: typing.Callable) -> event_base.BaseEvent:
         # we ignore headers, since the whole CE is in request body
         event = self.event
-        event.UnmarshalJSON(body)
+        event.UnmarshalJSON(body, data_unmarshaller)
         return event
 
     def write(self,
               event: event_base.BaseEvent,
               data_marshaller: typing.Callable) -> (dict, typing.IO):
-        return {}, event.MarshalJSON()
+        if not isinstance(data_marshaller, typing.Callable):
+            raise exceptions.InvalidDataMarshaller()
+
+        return {}, event.MarshalJSON(data_marshaller)
 
 
 def NewJSONHTTPCloudEventConverter(

cloudevents/sdk/event/base.py

@@ -114,15 +114,21 @@ def Set(self, key: str, value: object):
         exts.update({key: value})
         self.Set("extensions", exts)
 
-    def MarshalJSON(self) -> typing.IO:
-        return io.StringIO(ujson.dumps(self.Properties()))
+    def MarshalJSON(self, data_marshaller: typing.Callable) -> typing.IO:
+        props = self.Properties()
+        props["data"] = data_marshaller(props.get("data"))
+        return io.StringIO(ujson.dumps(props))
 
-    def UnmarshalJSON(self, b: typing.IO):
+    def UnmarshalJSON(self, b: typing.IO,
+                      data_unmarshaller: typing.Callable):
         raw_ce = ujson.load(b)
         for name, value in raw_ce.items():
+            if name == "data":
+                value = data_unmarshaller(value)
             self.Set(name, value)
 
-    def UnmarshalBinary(self, headers: dict, body: typing.IO):
+    def UnmarshalBinary(self, headers: dict, body: typing.IO,
+                        data_unmarshaller: typing.Callable):
         props = self.Properties(with_nullable=True)
         exts = props.get("extensions")
         for key in props:
@@ -133,15 +139,9 @@ def UnmarshalBinary(self, headers: dict, body: typing.IO):
                     del headers[formatted_key]
 
         # rest of headers suppose to an extension?
-
         exts.update(**headers)
         self.Set("extensions", exts)
-
-        data = None
-        if body:
-            data = body.read()
-
-        self.Set("data", data)
+        self.Set("data", data_unmarshaller(body))
 
     def MarshalBinary(self) -> (dict, object):
         headers = {}

cloudevents/sdk/exceptions.py

@@ -13,15 +13,29 @@
 #    under the License.
 
 
-class InvalidMimeType(Exception):
+class InvalidMimeTypeFromRequest(Exception):
 
     def __init__(self, mime_type):
         super().__init__(
-            "Invalid MIME type: {0}".format(mime_type))
+            "Unable to read CloudEvent from request, "
+            "invalid MIME type: {0}".format(mime_type))
 
 
 class UnsupportedEvent(Exception):
 
     def __init__(self, event_class):
         super().__init__("Invalid CloudEvent class: "
                          "'{0}'".format(event_class))
+
+
+class InvalidDataMarshaller(Exception):
+
+    def __init__(self):
+        super().__init__(
+            "Invalid data marshaller, is not a callable")
+
+
+class NoSuchConverter(Exception):
+    def __init__(self, converter_type):
+        super().__init__(
+            "No such converter {0}".format(converter_type))

cloudevents/sdk/marshaller.py

@@ -24,28 +24,72 @@
 
 
 class HTTPMarshaller(object):
+    """
+    HTTP Marshaller class.
+    API of this class designed to work with CloudEvent (upstream and v0.1)
+    """
 
     def __init__(self, converters: typing.List[base.Converter]):
-        self.__converters = converters
+        """
+        CloudEvent HTTP marshaller constructor
+        :param converters: a list of HTTP-to-CloudEvent-to-HTTP constructors
+        :type converters: typing.List[base.Converter]
+        """
+        self.__converters = {c.TYPE: c for c in converters}
 
-    def FromRequest(self, headers: dict, body: typing.IO):
+    def FromRequest(self, headers: dict,
+                    body: typing.IO,
+                    data_unmarshaller:
+                    typing.Callable) -> event_base.BaseEvent:
+        """
+        Reads a CloudEvent from an HTTP headers and request body
+        :param headers: a dict-like HTTP headers
+        :type headers: dict
+        :param body: a stream-like HTTP request body
+        :type body: typing.IO
+        :param data_unmarshaller: a callable-like
+                                  unmarshaller the CloudEvent data
+        :return: a CloudEvent
+        :rtype: event_base.BaseEvent
+        """
         mimeType = headers.get("Content-Type")
-        for cnvrtr in self.__converters:
+        for _, cnvrtr in self.__converters.items():
             if cnvrtr.can_read(mimeType):
-                return cnvrtr.read(headers, body)
+                return cnvrtr.read(headers, body, data_unmarshaller)
 
-        raise exceptions.InvalidMimeType(mimeType)
+        raise exceptions.InvalidMimeTypeFromRequest(mimeType)
 
     def ToRequest(self, event: event_base.BaseEvent,
                   converter_type: str,
                   data_marshaller: typing.Callable) -> (dict, typing.IO):
-        for cnvrtv in self.__converters:
-            if converter_type == cnvrtv.TYPE:
-                return cnvrtv.write(event, data_marshaller)
+        """
+        Writes a CloudEvent into a HTTP-ready form of headers and request body
+        :param event: CloudEvent
+        :type event: event_base.BaseEvent
+        :param converter_type: a type of CloudEvent-to-HTTP converter
+        :type converter_type: str
+        :param data_marshaller: a callable-like marshaller CloudEvent data
+        :type data_marshaller: typing.Callable
+        :return: dict of HTTP headers and stream of HTTP request body
+        :rtype: tuple
+        """
+        if converter_type in self.__converters:
+            cnvrtr = self.__converters.get(converter_type)
+            return cnvrtr.write(event, data_marshaller)
+
+        raise exceptions.NoSuchConverter(converter_type)
 
 
 def NewDefaultHTTPMarshaller(
         event_class: event_base.BaseEvent) -> HTTPMarshaller:
+    """
+    Creates the default HTTP marshaller with both structured
+        and binary converters
+    :param event_class: CloudEvent spec class
+    :type event_class: event_base.BaseEvent
+    :return: an instance of HTTP marshaller
+    :rtype: cloudevents.sdk.marshaller.HTTPMarshaller
+    """
     return HTTPMarshaller([
         structured.NewJSONHTTPCloudEventConverter(event_class),
         binary.NewBinaryHTTPCloudEventConverter(event_class),
@@ -54,4 +98,12 @@ def NewDefaultHTTPMarshaller(
 
 def NewHTTPMarshaller(
         converters: typing.List[base.Converter]) -> HTTPMarshaller:
+    """
+    Creates the default HTTP marshaller with both
+        structured and binary converters
+    :param converters: a list of CloudEvent-to-HTTP-to-CloudEvent converters
+    :type converters: typing.List[base.Converter]
+    :return: an instance of HTTP marshaller
+    :rtype: cloudevents.sdk.marshaller.HTTPMarshaller
+    """
     return HTTPMarshaller(converters)

cloudevents/tests/test_event_from_request_converter.py

@@ -34,7 +34,7 @@ def test_binary_converter_upstream():
             binary.NewBinaryHTTPCloudEventConverter(upstream.Event)
         ]
     )
-    event = m.FromRequest(data.headers, None)
+    event = m.FromRequest(data.headers, None, lambda x: x)
     assert event is not None
     assert event.Get("type") == (data.ce_type, True)
     assert event.Get("id") == (data.ce_id, True)
@@ -48,7 +48,8 @@ def test_structured_converter_upstream():
     )
     event = m.FromRequest(
         {"Content-Type": "application/cloudevents+json"},
-        io.StringIO(ujson.dumps(data.ce))
+        io.StringIO(ujson.dumps(data.ce)),
+        lambda x: x.read()
     )
 
     assert event is not None
@@ -72,7 +73,8 @@ def test_structured_converter_v01():
     )
     event = m.FromRequest(
         {"Content-Type": "application/cloudevents+json"},
-        io.StringIO(ujson.dumps(data.ce))
+        io.StringIO(ujson.dumps(data.ce)),
+        lambda x: x.read()
     )
 
     assert event is not None
@@ -85,7 +87,8 @@ def test_default_http_marshaller():
 
     event = m.FromRequest(
         {"Content-Type": "application/cloudevents+json"},
-        io.StringIO(ujson.dumps(data.ce))
+        io.StringIO(ujson.dumps(data.ce)),
+        lambda x: x.read()
     )
     assert event is not None
     assert event.Get("type") == (data.ce_type, True)

cloudevents/tests/test_event_to_request_converter.py

@@ -31,7 +31,8 @@ def test_binary_event_to_request_upstream():
     m = marshaller.NewDefaultHTTPMarshaller(upstream.Event)
     event = m.FromRequest(
         {"Content-Type": "application/cloudevents+json"},
-        io.StringIO(ujson.dumps(data.ce))
+        io.StringIO(ujson.dumps(data.ce)),
+        lambda x: x.read()
     )
 
     assert event is not None
@@ -48,7 +49,9 @@ def test_structured_event_to_request_upstream():
     m = marshaller.NewDefaultHTTPMarshaller(upstream.Event)
     event = m.FromRequest(
         {"Content-Type": "application/cloudevents+json"},
-        io.StringIO(ujson.dumps(data.ce)))
+        io.StringIO(ujson.dumps(data.ce)),
+        lambda x: x.read()
+    )
     assert event is not None
     assert event.Get("type") == (data.ce_type, True)
     assert event.Get("id") == (data.ce_id, True)
@@ -67,7 +70,9 @@ def test_structured_event_to_request_v01():
     )
     event = m.FromRequest(
         {"Content-Type": "application/cloudevents+json"},
-        io.StringIO(ujson.dumps(data.ce)))
+        io.StringIO(ujson.dumps(data.ce)),
+        lambda x: x.read()
+    )
     assert event is not None
     assert event.Get("type") == (data.ce_type, True)
     assert event.Get("id") == (data.ce_id, True)