feat: implementation for JSON format.

pyproject.toml

@@ -32,6 +32,7 @@ keywords = [
 ]
 dependencies = [
     "ruff>=0.6.8",
+    "python-dateutil>=2.8.2",
 ]
 
 [project.urls]
@@ -53,6 +54,7 @@ dev-dependencies = [
     "flake8-print>=5.0.0",
     "pre-commit>=3.8.0",
     "pytest-cov>=5.0.0",
+    "types-python-dateutil>=2.9.0.20241003",
 ]
 
 [tool.uv.pip]

src/cloudevents/core/base.py

@@ -0,0 +1,45 @@
+#  Copyright 2018-Present The CloudEvents Authors
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+
+from datetime import datetime
+from typing import Any, Optional, Protocol, Union
+
+
+class BaseCloudEvent(Protocol):
+    def __init__(
+        self, attributes: dict[str, Any], data: Optional[Union[dict, str, bytes]] = None
+    ) -> None: ...
+
+    def get_id(self) -> str: ...
+
+    def get_source(self) -> str: ...
+
+    def get_type(self) -> str: ...
+
+    def get_specversion(self) -> str: ...
+
+    def get_datacontenttype(self) -> Optional[str]: ...
+
+    def get_dataschema(self) -> Optional[str]: ...
+
+    def get_subject(self) -> Optional[str]: ...
+
+    def get_time(self) -> Optional[datetime]: ...
+
+    def get_extension(self, extension_name: str) -> Any: ...
+
+    def get_data(self) -> Optional[Union[dict, str, bytes]]: ...
+
+    def get_attributes(self) -> dict[str, Any]: ...

src/cloudevents/core/formats/__init__.py

@@ -0,0 +1,13 @@
+#  Copyright 2018-Present The CloudEvents Authors
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.

src/cloudevents/core/formats/base.py

@@ -0,0 +1,30 @@
+#  Copyright 2018-Present The CloudEvents Authors
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+
+from typing import Callable, Optional, Protocol, Union
+
+from cloudevents.core.base import BaseCloudEvent
+
+
+class Format(Protocol):
+    def read(
+        self,
+        event_factory: Callable[
+            [dict, Optional[Union[dict, str, bytes]]], BaseCloudEvent
+        ],
+        data: Union[str, bytes],
+    ) -> BaseCloudEvent: ...
+
+    def write(self, event: BaseCloudEvent) -> bytes: ...

src/cloudevents/core/formats/json.py

@@ -0,0 +1,104 @@
+#  Copyright 2018-Present The CloudEvents Authors
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+
+import base64
+import re
+from datetime import datetime
+from json import JSONEncoder, dumps, loads
+from typing import Any, Callable, Final, Optional, Pattern, Union
+
+from dateutil.parser import isoparse  # type: ignore[import-untyped]
+
+from cloudevents.core.base import BaseCloudEvent
+from cloudevents.core.formats.base import Format
+
+
+class _JSONEncoderWithDatetime(JSONEncoder):
+    """
+    Custom JSON encoder to handle datetime objects in the format required by the CloudEvents spec.
+    """
+
+    def default(self, obj: Any) -> Any:
+        if isinstance(obj, datetime):
+            dt = obj.isoformat()
+            # 'Z' denotes a UTC offset of 00:00 see
+            # https://www.rfc-editor.org/rfc/rfc3339#section-2
+            if dt.endswith("+00:00"):
+                dt = dt.removesuffix("+00:00") + "Z"
+            return dt
+
+        return super().default(obj)
+
+
+class JSONFormat(Format):
+    CONTENT_TYPE: Final[str] = "application/cloudevents+json"
+    JSON_CONTENT_TYPE_PATTERN: Pattern[str] = re.compile(
+        r"^(application|text)/([a-zA-Z0-9\-\.]+\+)?json(;.*)?$"
+    )
+
+    def read(
+        self,
+        event_factory: Callable[
+            [dict, Optional[Union[dict, str, bytes]]], BaseCloudEvent
+        ],
+        data: Union[str, bytes],
+    ) -> BaseCloudEvent:
+        """
+        Read a CloudEvent from a JSON formatted byte string.
+
+        :param event_factory: A factory function to create CloudEvent instances.
+        :param data: The JSON formatted byte array.
+        :return: The CloudEvent instance.
+        """
+        decoded_data: str
+        if isinstance(data, bytes):
+            decoded_data = data.decode("utf-8")
+        else:
+            decoded_data = data
+
+        event_attributes = loads(decoded_data)
+
+        if "time" in event_attributes:
+            event_attributes["time"] = isoparse(event_attributes["time"])
+
+        event_data: Union[dict, str, bytes, None] = event_attributes.pop("data", None)
+        if event_data is None:
+            event_data_base64 = event_attributes.pop("data_base64", None)
+            if event_data_base64 is not None:
+                event_data = base64.b64decode(event_data_base64)
+
+        return event_factory(event_attributes, event_data)
+
+    def write(self, event: BaseCloudEvent) -> bytes:
+        """
+        Write a CloudEvent to a JSON formatted byte string.
+
+        :param event: The CloudEvent to write.
+        :return: The CloudEvent as a JSON formatted byte array.
+        """
+        event_data = event.get_data()
+        event_dict: dict[str, Any] = dict(event.get_attributes())
+
+        if event_data is not None:
+            if isinstance(event_data, (bytes, bytearray)):
+                event_dict["data_base64"] = base64.b64encode(event_data).decode("utf-8")
+            else:
+                datacontenttype = event_dict.get("datacontenttype", "application/json")
+                if re.match(JSONFormat.JSON_CONTENT_TYPE_PATTERN, datacontenttype):
+                    event_dict["data"] = event_data
+                else:
+                    event_dict["data"] = str(event_data)
+
+        return dumps(event_dict, cls=_JSONEncoderWithDatetime).encode("utf-8")

src/cloudevents/core/v1/event.py

@@ -15,8 +15,9 @@
 import re
 from collections import defaultdict
 from datetime import datetime
-from typing import Any, Final, Optional
+from typing import Any, Final, Optional, Union
 
+from cloudevents.core.base import BaseCloudEvent
 from cloudevents.core.v1.exceptions import (
     BaseCloudEventException,
     CloudEventValidationError,
@@ -35,7 +36,7 @@
 ]
 
 
-class CloudEvent:
+class CloudEvent(BaseCloudEvent):
     """
     The CloudEvent Python wrapper contract exposing generically-available
     properties and APIs.
@@ -44,7 +45,9 @@ class CloudEvent:
     obliged to follow this contract.
     """
 
-    def __init__(self, attributes: dict[str, Any], data: Optional[dict] = None) -> None:
+    def __init__(
+        self, attributes: dict[str, Any], data: Optional[Union[dict, str, bytes]] = None
+    ) -> None:
         """
         Create a new CloudEvent instance.
 
@@ -56,7 +59,7 @@ def __init__(self, attributes: dict[str, Any], data: Optional[dict] = None) -> N
         """
         self._validate_attribute(attributes=attributes)
         self._attributes: dict[str, Any] = attributes
-        self._data: Optional[dict] = data
+        self._data: Optional[Union[dict, str, bytes]] = data
 
     @staticmethod
     def _validate_attribute(attributes: dict[str, Any]) -> None:
@@ -315,10 +318,18 @@ def get_extension(self, extension_name: str) -> Any:
         """
         return self._attributes.get(extension_name)
 
-    def get_data(self) -> Optional[dict]:
+    def get_data(self) -> Optional[Union[dict, str, bytes]]:
         """
         Retrieve data of the event.
 
         :return: The data of the event.
         """
         return self._data
+
+    def get_attributes(self) -> dict[str, Any]:
+        """
+        Retrieve all attributes of the event.
+
+        :return: The attributes of the event.
+        """
+        return self._attributes

tests/test_core/test_format/__init__.py

@@ -0,0 +1,13 @@
+#  Copyright 2018-Present The CloudEvents Authors
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.