chore: improve typing of functions returning AnyCloudEvent

kafka.conversion.from_binary() and from_structured() return
AnyCloudEvent type var according to their event_type argument, but when
event_type is None, type checkers cannot infer the return type. We now
use an overload to declare that the return type is http.CloudEvent when
event_type is None.

Previously users had to explicitly annotate this type when calling
without event_type. This happens quite a lot in this repo's
test_kafka_conversions.py — this fixes quite a few type errors like:

> error: Need type annotation for "result"  [var-annotated]

Signed-off-by: Hal Blackburn <[email protected]>

Author: h4l

cloudevents/kafka/conversion.py

@@ -111,11 +111,29 @@ def to_binary(
     return KafkaMessage(headers, message_key, data)
 
 
+@typing.overload
 def from_binary(
     message: KafkaMessage,
-    event_type: typing.Optional[typing.Type[AnyCloudEvent]] = None,
+    event_type: None = None,
+    data_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
+) -> http.CloudEvent:
+    pass
+
+
+@typing.overload
+def from_binary(
+    message: KafkaMessage,
+    event_type: typing.Type[AnyCloudEvent],
     data_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
 ) -> AnyCloudEvent:
+    pass
+
+
+def from_binary(
+    message: KafkaMessage,
+    event_type: typing.Optional[typing.Type[AnyCloudEvent]] = None,
+    data_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
+) -> typing.Union[http.CloudEvent, AnyCloudEvent]:
     """
     Returns a CloudEvent from a KafkaMessage in binary format.
 
@@ -144,10 +162,11 @@ def from_binary(
         raise cloud_exceptions.DataUnmarshallerError(
             f"Failed to unmarshall data with error: {type(e).__name__}('{e}')"
         )
+    result: typing.Union[http.CloudEvent, AnyCloudEvent]
     if event_type:
         result = event_type.create(attributes, data)
     else:
-        result = http.CloudEvent.create(attributes, data)  # type: ignore
+        result = http.CloudEvent.create(attributes, data)
     return result
 
 
@@ -210,12 +229,32 @@ def to_structured(
     return KafkaMessage(headers, message_key, value)
 
 
+@typing.overload
 def from_structured(
     message: KafkaMessage,
-    event_type: typing.Optional[typing.Type[AnyCloudEvent]] = None,
+    event_type: None = None,
+    data_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
+    envelope_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
+) -> http.CloudEvent:
+    pass
+
+
+@typing.overload
+def from_structured(
+    message: KafkaMessage,
+    event_type: typing.Type[AnyCloudEvent],
     data_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
     envelope_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
 ) -> AnyCloudEvent:
+    pass
+
+
+def from_structured(
+    message: KafkaMessage,
+    event_type: typing.Optional[typing.Type[AnyCloudEvent]] = None,
+    data_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
+    envelope_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
+) -> typing.Union[http.CloudEvent, AnyCloudEvent]:
     """
     Returns a CloudEvent from a KafkaMessage in structured format.
 
@@ -264,8 +303,9 @@ def from_structured(
             attributes["datacontenttype"] = val.decode()
         else:
             attributes[header.lower()] = val.decode()
+    result: typing.Union[AnyCloudEvent, http.CloudEvent]
     if event_type:
         result = event_type.create(attributes, data)
     else:
-        result = http.CloudEvent.create(attributes, data)  # type: ignore
+        result = http.CloudEvent.create(attributes, data)
     return result