Introduce typings (#207)

* chore: Add pre-commit hook

Signed-off-by: Yurii Serhiichuk <[email protected]>

* chore: address typing issues

Signed-off-by: Yurii Serhiichuk <[email protected]>

* chore: add py.typed meta

Signed-off-by: Yurii Serhiichuk <[email protected]>

* Add Pydantic plugin

Signed-off-by: Yurii Serhiichuk <[email protected]>

* Add Pydantic dependency

Signed-off-by: Yurii Serhiichuk <[email protected]>

* Add MyPy best practices configs

Signed-off-by: Yurii Serhiichuk <[email protected]>

* Add deprecation MyPy ignore

Signed-off-by: Yurii Serhiichuk <[email protected]>

* chore: more typing fixes

Signed-off-by: Yurii Serhiichuk <[email protected]>

* chore: more typings and explicit optionals

Signed-off-by: Yurii Serhiichuk <[email protected]>

* Use lowest-supported Python version

Signed-off-by: Yurii Serhiichuk <[email protected]>

* chore: Fix silly `dict` and other MyPy-related issues.

We're now explicitly ensuring codebase supports Python3.7+

Signed-off-by: Yurii Serhiichuk <[email protected]>

* chore: ignore typing limitation

Signed-off-by: Yurii Serhiichuk <[email protected]>

* chore: `not` with `dict` returns `false` for an empty dict, so use `is None` check

Signed-off-by: Yurii Serhiichuk <[email protected]>

* deps: Update hooks

Signed-off-by: Yurii Serhiichuk <[email protected]>

* chore: Make sure only non-callable unmarshallers are flagged

Signed-off-by: Yurii Serhiichuk <[email protected]>

* chore: Have some coverage slack

Signed-off-by: Yurii Serhiichuk <[email protected]>

* deps: bump pre-commit-hooks

Signed-off-by: Yurii Serhiichuk <[email protected]>

* ci: make sure py.typed is included into the bundle

Signed-off-by: Yurii Serhiichuk <[email protected]>

* docs: improve setup.py setup and add missing package metadata

Signed-off-by: Yurii Serhiichuk <[email protected]>

Signed-off-by: Yurii Serhiichuk <[email protected]>

Author: xSAVIKx

.pre-commit-config.yaml

@@ -1,17 +1,27 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
+    rev: v4.4.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-toml
   - repo: https://github.com/pycqa/isort
-    rev: 5.10.1
+    rev: 5.11.4
     hooks:
       - id: isort
         args: [ "--profile", "black", "--filter-files" ]
   - repo: https://github.com/psf/black
-    rev: 22.10.0
+    rev: 22.12.0
     hooks:
       - id: black
         language_version: python3.10
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: "v0.991"
+    hooks:
+      - id: mypy
+        files: ^(cloudevents/)
+        exclude: ^(cloudevents/tests/)
+        types: [ python ]
+        args: [ ]
+        additional_dependencies:
+          - 'pydantic'

MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include CHANGELOG.md
+include LICENSE
+include cloudevents/py.typed

cloudevents/abstract/__init__.py

@@ -14,4 +14,4 @@
 
 from cloudevents.abstract.event import AnyCloudEvent, CloudEvent
 
-__all__ = [AnyCloudEvent, CloudEvent]
+__all__ = ["AnyCloudEvent", "CloudEvent"]

cloudevents/abstract/event.py

@@ -17,6 +17,8 @@
 from types import MappingProxyType
 from typing import Mapping
 
+AnyCloudEvent = typing.TypeVar("AnyCloudEvent", bound="CloudEvent")
+
 
 class CloudEvent:
     """
@@ -29,10 +31,10 @@ class CloudEvent:
 
     @classmethod
     def create(
-        cls,
+        cls: typing.Type[AnyCloudEvent],
         attributes: typing.Dict[str, typing.Any],
         data: typing.Optional[typing.Any],
-    ) -> "AnyCloudEvent":
+    ) -> AnyCloudEvent:
         """
         Creates a new instance of the CloudEvent using supplied `attributes`
         and `data`.
@@ -70,7 +72,7 @@ def _get_attributes(self) -> typing.Dict[str, typing.Any]:
         raise NotImplementedError()
 
     @abstractmethod
-    def _get_data(self) -> typing.Optional[typing.Any]:
+    def get_data(self) -> typing.Optional[typing.Any]:
         """
         Returns the data of the event.
 
@@ -85,7 +87,7 @@ def _get_data(self) -> typing.Optional[typing.Any]:
 
     def __eq__(self, other: typing.Any) -> bool:
         if isinstance(other, CloudEvent):
-            same_data = self._get_data() == other._get_data()
+            same_data = self.get_data() == other.get_data()
             same_attributes = self._get_attributes() == other._get_attributes()
             return same_data and same_attributes
         return False
@@ -140,7 +142,4 @@ def __contains__(self, key: str) -> bool:
         return key in self._get_attributes()
 
     def __repr__(self) -> str:
-        return str({"attributes": self._get_attributes(), "data": self._get_data()})
-
-
-AnyCloudEvent = typing.TypeVar("AnyCloudEvent", bound=CloudEvent)
+        return str({"attributes": self._get_attributes(), "data": self.get_data()})

cloudevents/conversion.py

@@ -23,7 +23,7 @@
 from cloudevents.sdk.event import v1, v03
 
 
-def _best_effort_serialize_to_json(
+def _best_effort_serialize_to_json(  # type: ignore[no-untyped-def]
     value: typing.Any, *args, **kwargs
 ) -> typing.Optional[typing.Union[bytes, str, typing.Any]]:
     """
@@ -43,18 +43,18 @@ def _best_effort_serialize_to_json(
         return value
 
 
-_default_marshaller_by_format = {
+_default_marshaller_by_format: typing.Dict[str, types.MarshallerType] = {
     converters.TypeStructured: lambda x: x,
     converters.TypeBinary: _best_effort_serialize_to_json,
-}  # type: typing.Dict[str, types.MarshallerType]
+}
 
 _obj_by_version = {"1.0": v1.Event, "0.3": v03.Event}
 
 
 def to_json(
     event: AnyCloudEvent,
-    data_marshaller: types.MarshallerType = None,
-) -> typing.Union[str, bytes]:
+    data_marshaller: typing.Optional[types.MarshallerType] = None,
+) -> bytes:
     """
     Converts given `event` to a JSON string.
 
@@ -69,7 +69,7 @@ def to_json(
 def from_json(
     event_type: typing.Type[AnyCloudEvent],
     data: typing.Union[str, bytes],
-    data_unmarshaller: types.UnmarshallerType = None,
+    data_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
 ) -> AnyCloudEvent:
     """
     Parses JSON string `data` into a CloudEvent.
@@ -91,9 +91,9 @@ def from_json(
 
 def from_http(
     event_type: typing.Type[AnyCloudEvent],
-    headers: typing.Dict[str, str],
-    data: typing.Union[str, bytes, None],
-    data_unmarshaller: types.UnmarshallerType = None,
+    headers: typing.Mapping[str, str],
+    data: typing.Optional[typing.Union[str, bytes]],
+    data_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
 ) -> AnyCloudEvent:
     """
     Parses CloudEvent `data` and `headers` into an instance of a given `event_type`.
@@ -133,14 +133,14 @@ def from_http(
         except json.decoder.JSONDecodeError:
             raise cloud_exceptions.MissingRequiredFields(
                 "Failed to read specversion from both headers and data. "
-                f"The following can not be parsed as json: {data}"
+                "The following can not be parsed as json: {!r}".format(data)
             )
         if hasattr(raw_ce, "get"):
             specversion = raw_ce.get("specversion", None)
         else:
             raise cloud_exceptions.MissingRequiredFields(
                 "Failed to read specversion from both headers and data. "
-                f"The following deserialized data has no 'get' method: {raw_ce}"
+                "The following deserialized data has no 'get' method: {}".format(raw_ce)
             )
 
     if specversion is None:
@@ -152,7 +152,7 @@ def from_http(
 
     if event_handler is None:
         raise cloud_exceptions.InvalidRequiredFields(
-            f"Found invalid specversion {specversion}"
+            "Found invalid specversion {}".format(specversion)
         )
 
     event = marshall.FromRequest(
@@ -163,20 +163,19 @@ def from_http(
     attrs.pop("extensions", None)
     attrs.update(**event.extensions)
 
+    result_data: typing.Optional[typing.Any] = event.data
     if event.data == "" or event.data == b"":
         # TODO: Check binary unmarshallers to debug why setting data to ""
-        # returns an event with data set to None, but structured will return ""
-        data = None
-    else:
-        data = event.data
-    return event_type.create(attrs, data)
+        #  returns an event with data set to None, but structured will return ""
+        result_data = None
+    return event_type.create(attrs, result_data)
 
 
 def _to_http(
     event: AnyCloudEvent,
     format: str = converters.TypeStructured,
-    data_marshaller: types.MarshallerType = None,
-) -> typing.Tuple[dict, typing.Union[bytes, str]]:
+    data_marshaller: typing.Optional[types.MarshallerType] = None,
+) -> typing.Tuple[typing.Dict[str, str], bytes]:
     """
     Returns a tuple of HTTP headers/body dicts representing this Cloud Event.
 
@@ -196,7 +195,7 @@ def _to_http(
     event_handler = _obj_by_version[event["specversion"]]()
     for attribute_name in event:
         event_handler.Set(attribute_name, event[attribute_name])
-    event_handler.data = event.data
+    event_handler.data = event.get_data()
 
     return marshaller.NewDefaultHTTPMarshaller().ToRequest(
         event_handler, format, data_marshaller=data_marshaller
@@ -205,8 +204,8 @@ def _to_http(
 
 def to_structured(
     event: AnyCloudEvent,
-    data_marshaller: types.MarshallerType = None,
-) -> typing.Tuple[dict, typing.Union[bytes, str]]:
+    data_marshaller: typing.Optional[types.MarshallerType] = None,
+) -> typing.Tuple[typing.Dict[str, str], bytes]:
     """
     Returns a tuple of HTTP headers/body dicts representing this Cloud Event.
 
@@ -222,8 +221,8 @@ def to_structured(
 
 
 def to_binary(
-    event: AnyCloudEvent, data_marshaller: types.MarshallerType = None
-) -> typing.Tuple[dict, typing.Union[bytes, str]]:
+    event: AnyCloudEvent, data_marshaller: typing.Optional[types.MarshallerType] = None
+) -> typing.Tuple[typing.Dict[str, str], bytes]:
     """
     Returns a tuple of HTTP headers/body dicts representing this Cloud Event.
 
@@ -287,19 +286,13 @@ def to_dict(event: AnyCloudEvent) -> typing.Dict[str, typing.Any]:
     :returns: The canonical dict representation of the event.
     """
     result = {attribute_name: event.get(attribute_name) for attribute_name in event}
-    result["data"] = event.data
+    result["data"] = event.get_data()
     return result
 
 
 def _json_or_string(
-    content: typing.Optional[typing.AnyStr],
-) -> typing.Optional[
-    typing.Union[
-        typing.Dict[typing.Any, typing.Any],
-        typing.List[typing.Any],
-        typing.AnyStr,
-    ]
-]:
+    content: typing.Optional[typing.Union[str, bytes]],
+) -> typing.Any:
     """
     Returns a JSON-decoded dictionary or a list of dictionaries if
     a valid JSON string is provided.

cloudevents/http/__init__.py

@@ -25,15 +25,15 @@
 from cloudevents.http.json_methods import to_json  # deprecated
 
 __all__ = [
-    to_binary,
-    to_structured,
-    from_json,
-    from_http,
-    from_dict,
-    CloudEvent,
-    is_binary,
-    is_structured,
-    to_binary_http,
-    to_structured_http,
-    to_json,
+    "to_binary",
+    "to_structured",
+    "from_json",
+    "from_http",
+    "from_dict",
+    "CloudEvent",
+    "is_binary",
+    "is_structured",
+    "to_binary_http",
+    "to_structured_http",
+    "to_json",
 ]

cloudevents/http/conversion.py

@@ -23,7 +23,7 @@
 
 def from_json(
     data: typing.Union[str, bytes],
-    data_unmarshaller: types.UnmarshallerType = None,
+    data_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
 ) -> CloudEvent:
     """
     Parses JSON string `data` into a CloudEvent.
@@ -38,8 +38,8 @@ def from_json(
 
 def from_http(
     headers: typing.Dict[str, str],
-    data: typing.Union[str, bytes, None],
-    data_unmarshaller: types.UnmarshallerType = None,
+    data: typing.Optional[typing.Union[str, bytes]],
+    data_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
 ) -> CloudEvent:
     """
     Parses CloudEvent `data` and `headers` into a CloudEvent`.

cloudevents/http/event.py

@@ -82,7 +82,7 @@ def __init__(self, attributes: typing.Dict[str, str], data: typing.Any = None):
     def _get_attributes(self) -> typing.Dict[str, typing.Any]:
         return self._attributes
 
-    def _get_data(self) -> typing.Optional[typing.Any]:
+    def get_data(self) -> typing.Optional[typing.Any]:
         return self.data
 
     def __setitem__(self, key: str, value: typing.Any) -> None:

cloudevents/http/http_methods.py

@@ -31,8 +31,8 @@
     details="Use cloudevents.conversion.to_binary function instead",
 )
 def to_binary(
-    event: AnyCloudEvent, data_marshaller: types.MarshallerType = None
-) -> typing.Tuple[dict, typing.Union[bytes, str]]:
+    event: AnyCloudEvent, data_marshaller: typing.Optional[types.MarshallerType] = None
+) -> typing.Tuple[typing.Dict[str, str], bytes]:
     return _moved_to_binary(event, data_marshaller)
 
 
@@ -42,8 +42,8 @@ def to_binary(
 )
 def to_structured(
     event: AnyCloudEvent,
-    data_marshaller: types.MarshallerType = None,
-) -> typing.Tuple[dict, typing.Union[bytes, str]]:
+    data_marshaller: typing.Optional[types.MarshallerType] = None,
+) -> typing.Tuple[typing.Dict[str, str], bytes]:
     return _moved_to_structured(event, data_marshaller)
 
 
@@ -53,21 +53,21 @@ def to_structured(
 )
 def from_http(
     headers: typing.Dict[str, str],
-    data: typing.Union[str, bytes, None],
-    data_unmarshaller: types.UnmarshallerType = None,
+    data: typing.Optional[typing.AnyStr],
+    data_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
 ) -> CloudEvent:
     return _moved_from_http(headers, data, data_unmarshaller)
 
 
 @deprecated(deprecated_in="1.0.2", details="Use to_binary function instead")
 def to_binary_http(
-    event: CloudEvent, data_marshaller: types.MarshallerType = None
-) -> typing.Tuple[dict, typing.Union[bytes, str]]:
+    event: CloudEvent, data_marshaller: typing.Optional[types.MarshallerType] = None
+) -> typing.Tuple[typing.Dict[str, str], bytes]:
     return _moved_to_binary(event, data_marshaller)
 
 
 @deprecated(deprecated_in="1.0.2", details="Use to_structured function instead")
 def to_structured_http(
-    event: CloudEvent, data_marshaller: types.MarshallerType = None
-) -> typing.Tuple[dict, typing.Union[bytes, str]]:
+    event: CloudEvent, data_marshaller: typing.Optional[types.MarshallerType] = None
+) -> typing.Tuple[typing.Dict[str, str], bytes]:
     return _moved_to_structured(event, data_marshaller)

cloudevents/http/json_methods.py

@@ -31,8 +31,8 @@
 )
 def to_json(
     event: AnyCloudEvent,
-    data_marshaller: types.MarshallerType = None,
-) -> typing.Union[str, bytes]:
+    data_marshaller: typing.Optional[types.MarshallerType] = None,
+) -> bytes:
     return _moved_to_json(event, data_marshaller)
 
 
@@ -42,6 +42,6 @@ def to_json(
 )
 def from_json(
     data: typing.Union[str, bytes],
-    data_unmarshaller: types.UnmarshallerType = None,
+    data_unmarshaller: typing.Optional[types.UnmarshallerType] = None,
 ) -> CloudEvent:
     return _moved_from_json(data, data_unmarshaller)