feat(v2): add support for spec version 0.3 (#261)

* feat: add support for spec version 0.3

Signed-off-by: Tudor Plugaru <plugaru.tudor@protonmail.com>

* chore: make ruff fail on unused imports

Signed-off-by: Tudor Plugaru <plugaru.tudor@protonmail.com>

* chore: Move spec version constants to spec module

Moves SPECVERSION_V1_0 and SPECVERSION_V0_3 from the core __init__.py to
a new cloudevents.core.spec module.

Signed-off-by: Tudor Plugaru <plugaru.tudor@protonmail.com>

---------

Signed-off-by: Tudor Plugaru <plugaru.tudor@protonmail.com>

Author: PlugaruT

README.md

@@ -10,6 +10,7 @@ will) break with every update.
 This SDK current supports the following versions of CloudEvents:
 
 - v1.0
+- v0.3
 
 ## Python SDK
 

pyproject.toml

@@ -114,7 +114,10 @@ exclude = [
 [tool.ruff.lint]
 ignore = ["E731"]
 extend-ignore = ["E203"]
-select = ["I"]
+select = [
+    "I",    # isort - import sorting
+    "F401", # unused imports
+]
 
 
 [tool.pytest.ini_options]

src/cloudevents/core/bindings/amqp.py

@@ -19,8 +19,10 @@
 from dateutil.parser import isoparse
 
 from cloudevents.core.base import BaseCloudEvent, EventFactory
+from cloudevents.core.bindings.common import get_event_factory_for_version
 from cloudevents.core.formats.base import Format
 from cloudevents.core.formats.json import JSONFormat
+from cloudevents.core.spec import SPECVERSION_V1_0
 from cloudevents.core.v1.event import CloudEvent
 
 # AMQP CloudEvents spec allows both cloudEvents_ and cloudEvents: prefixes
@@ -151,11 +153,14 @@ def to_binary(event: BaseCloudEvent, event_format: Format) -> AMQPMessage:
 def from_binary(
     message: AMQPMessage,
     event_format: Format,
-    event_factory: EventFactory,
+    event_factory: EventFactory | None = None,
 ) -> BaseCloudEvent:
     """
     Parse an AMQP binary content mode message to a CloudEvent.
 
+    Auto-detects the CloudEvents version from the application properties
+    and uses the appropriate event factory if not explicitly provided.
+
     Extracts CloudEvent attributes from AMQP application properties with either
     'cloudEvents_' or 'cloudEvents:' prefix (per AMQP CloudEvents spec), and treats
     the AMQP 'content-type' property as the 'datacontenttype' attribute. The
@@ -202,6 +207,11 @@ def from_binary(
     if CONTENT_TYPE_PROPERTY in message.properties:
         attributes["datacontenttype"] = message.properties[CONTENT_TYPE_PROPERTY]
 
+    # Auto-detect version if factory not provided
+    if event_factory is None:
+        specversion = attributes.get("specversion", SPECVERSION_V1_0)
+        event_factory = get_event_factory_for_version(specversion)
+
     datacontenttype = attributes.get("datacontenttype")
     data = event_format.read_data(message.application_data, datacontenttype)
 
@@ -250,7 +260,7 @@ def to_structured(event: BaseCloudEvent, event_format: Format) -> AMQPMessage:
 def from_structured(
     message: AMQPMessage,
     event_format: Format,
-    event_factory: EventFactory,
+    event_factory: EventFactory | None = None,
 ) -> BaseCloudEvent:
     """
     Parse an AMQP structured content mode message to a CloudEvent.
@@ -259,33 +269,44 @@ def from_structured(
     specified format. Any cloudEvents_-prefixed application properties are ignored
     as the application-data contains all event metadata.
 
+    If event_factory is not provided, version detection is delegated to the format
+    implementation, which will auto-detect based on the 'specversion' field.
+
     Example:
         >>> from cloudevents.core.v1.event import CloudEvent
         >>> from cloudevents.core.formats.json import JSONFormat
         >>>
+        >>> # Explicit factory
         >>> message = AMQPMessage(
         ...     properties={"content-type": "application/cloudevents+json"},
         ...     application_properties={},
         ...     application_data=b'{"type": "com.example.test", "source": "/test", ...}'
         ... )
         >>> event = from_structured(message, JSONFormat(), CloudEvent)
+        >>>
+        >>> # Auto-detect version
+        >>> event = from_structured(message, JSONFormat())
 
     :param message: AMQPMessage to parse
     :param event_format: Format implementation for deserialization
-    :param event_factory: Factory function to create CloudEvent instances
+    :param event_factory: Factory function to create CloudEvent instances.
+                         If None, the format will auto-detect the version.
     :return: CloudEvent instance
     """
+    # Delegate version detection to format layer
     return event_format.read(event_factory, message.application_data)
 
 
 def from_amqp(
     message: AMQPMessage,
     event_format: Format,
-    event_factory: EventFactory,
+    event_factory: EventFactory | None = None,
 ) -> BaseCloudEvent:
     """
     Parse an AMQP message to a CloudEvent with automatic mode detection.
 
+    Auto-detects CloudEvents version and uses appropriate event factory if not provided.
+
     Automatically detects whether the message uses binary or structured content mode:
     - If content-type starts with "application/cloudevents" → structured mode
     - Otherwise → binary mode
@@ -315,7 +336,7 @@ def from_amqp(
 
     :param message: AMQPMessage to parse
     :param event_format: Format implementation for deserialization
-    :param event_factory: Factory function to create CloudEvent instances
+    :param event_factory: Factory function to create CloudEvent instances (auto-detected if None)
     :return: CloudEvent instance
     """
     content_type = message.properties.get(CONTENT_TYPE_PROPERTY, "")

src/cloudevents/core/bindings/common.py

@@ -25,6 +25,11 @@
 
 from dateutil.parser import isoparse
 
+from cloudevents.core.base import EventFactory
+from cloudevents.core.spec import SPECVERSION_V0_3
+from cloudevents.core.v03.event import CloudEvent as CloudEventV03
+from cloudevents.core.v1.event import CloudEvent
+
 TIME_ATTR: Final[str] = "time"
 CONTENT_TYPE_HEADER: Final[str] = "content-type"
 DATACONTENTTYPE_ATTR: Final[str] = "datacontenttype"
@@ -66,3 +71,19 @@ def decode_header_value(attr_name: str, value: str) -> Any:
         return isoparse(decoded)
 
     return decoded
+
+
+def get_event_factory_for_version(specversion: str) -> EventFactory:
+    """
+    Get the appropriate event factory based on the CloudEvents specification version.
+
+    This function returns the CloudEvent class implementation for the specified
+    version. Used by protocol bindings for automatic version detection.
+
+    :param specversion: The CloudEvents specification version (e.g., "0.3" or "1.0")
+    :return: EventFactory for the specified version (defaults to v1.0 for unknown versions)
+    """
+    if specversion == SPECVERSION_V0_3:
+        return CloudEventV03
+    # Default to v1.0 for unknown versions
+    return CloudEvent

src/cloudevents/core/bindings/http.py

@@ -21,10 +21,11 @@
     DATACONTENTTYPE_ATTR,
     decode_header_value,
     encode_header_value,
+    get_event_factory_for_version,
 )
 from cloudevents.core.formats.base import Format
 from cloudevents.core.formats.json import JSONFormat
-from cloudevents.core.v1.event import CloudEvent
+from cloudevents.core.spec import SPECVERSION_V1_0
 
 CE_PREFIX: Final[str] = "ce-"
 
@@ -94,11 +95,14 @@ def to_binary(event: BaseCloudEvent, event_format: Format) -> HTTPMessage:
 def from_binary(
     message: HTTPMessage,
     event_format: Format,
-    event_factory: EventFactory,
+    event_factory: EventFactory | None = None,
 ) -> BaseCloudEvent:
     """
     Parse an HTTP binary content mode message to a CloudEvent.
 
+    Auto-detects the CloudEvents version from the 'ce-specversion' header
+    and uses the appropriate event factory if not explicitly provided.
+
     Extracts CloudEvent attributes from ce-prefixed HTTP headers and treats the
     'Content-Type' header as the 'datacontenttype' attribute. The HTTP body is
     parsed as event data according to the content type.
@@ -116,7 +120,7 @@ def from_binary(
 
     :param message: HTTPMessage to parse
     :param event_format: Format implementation for data deserialization
-    :param event_factory: Factory function to create CloudEvent instances
+    :param event_factory: Factory function to create CloudEvent instances (auto-detected if None)
     :return: CloudEvent instance
     """
     attributes: dict[str, Any] = {}
@@ -130,6 +134,11 @@ def from_binary(
         elif normalized_name == CONTENT_TYPE_HEADER:
             attributes[DATACONTENTTYPE_ATTR] = header_value
 
+    # Auto-detect version if factory not provided
+    if event_factory is None:
+        specversion = attributes.get("specversion", SPECVERSION_V1_0)
+        event_factory = get_event_factory_for_version(specversion)
+
     datacontenttype = attributes.get(DATACONTENTTYPE_ATTR)
     data = event_format.read_data(message.body, datacontenttype)
 
@@ -172,40 +181,51 @@ def to_structured(event: BaseCloudEvent, event_format: Format) -> HTTPMessage:
 def from_structured(
     message: HTTPMessage,
     event_format: Format,
-    event_factory: EventFactory,
+    event_factory: EventFactory | None = None,
 ) -> BaseCloudEvent:
     """
     Parse an HTTP structured content mode message to a CloudEvent.
 
     Deserializes the CloudEvent from the HTTP body using the specified format.
     Any ce-prefixed headers are ignored as the body contains all event metadata.
 
+    If event_factory is not provided, version detection is delegated to the format
+    implementation, which will auto-detect based on the 'specversion' field.
+
     Example:
         >>> from cloudevents.core.v1.event import CloudEvent
         >>> from cloudevents.core.formats.json import JSONFormat
         >>>
+        >>> # Explicit factory (recommended for performance)
         >>> message = HTTPMessage(
         ...     headers={"content-type": "application/cloudevents+json"},
         ...     body=b'{"type": "com.example.test", "source": "/test", ...}'
         ... )
         >>> event = from_structured(message, JSONFormat(), CloudEvent)
+        >>>
+        >>> # Auto-detect version (convenient)
+        >>> event = from_structured(message, JSONFormat())
 
     :param message: HTTPMessage to parse
     :param event_format: Format implementation for deserialization
-    :param event_factory: Factory function to create CloudEvent instances
+    :param event_factory: Factory function to create CloudEvent instances.
+                         If None, the format will auto-detect the version.
     :return: CloudEvent instance
     """
+    # Delegate version detection to format layer
     return event_format.read(event_factory, message.body)
 
 
 def from_http(
     message: HTTPMessage,
     event_format: Format,
-    event_factory: EventFactory,
+    event_factory: EventFactory | None = None,
 ) -> BaseCloudEvent:
     """
     Parse an HTTP message to a CloudEvent with automatic mode detection.
 
+    Auto-detects CloudEvents version and uses appropriate event factory if not provided.
+
     Automatically detects whether the message uses binary or structured content mode:
     - If any ce- prefixed headers are present → binary mode
     - Otherwise → structured mode
@@ -233,7 +253,7 @@ def from_http(
 
     :param message: HTTPMessage to parse
     :param event_format: Format implementation for deserialization
-    :param event_factory: Factory function to create CloudEvent instances
+    :param event_factory: Factory function to create CloudEvent instances (auto-detected if None)
     :return: CloudEvent instance
     """
     if any(key.lower().startswith(CE_PREFIX) for key in message.headers.keys()):
@@ -271,21 +291,23 @@ def to_binary_event(
 def from_binary_event(
     message: HTTPMessage,
     event_format: Format | None = None,
-) -> CloudEvent:
+) -> BaseCloudEvent:
     """
-    Convenience wrapper for from_binary with JSON format and CloudEvent as defaults.
+    Convenience wrapper for from_binary with JSON format and auto-detection.
+
+    Auto-detects CloudEvents version (v0.3 or v1.0) from headers.
 
     Example:
         >>> from cloudevents.core.bindings import http
         >>> event = http.from_binary_event(message)
 
     :param message: HTTPMessage to parse
     :param event_format: Format implementation (defaults to JSONFormat)
-    :return: CloudEvent instance
+    :return: CloudEvent instance (v0.3 or v1.0 based on specversion)
     """
     if event_format is None:
         event_format = JSONFormat()
-    return from_binary(message, event_format, CloudEvent)
+    return from_binary(message, event_format, None)
 
 
 def to_structured_event(
@@ -317,39 +339,41 @@ def to_structured_event(
 def from_structured_event(
     message: HTTPMessage,
     event_format: Format | None = None,
-) -> CloudEvent:
+) -> BaseCloudEvent:
     """
-    Convenience wrapper for from_structured with JSON format and CloudEvent as defaults.
+    Convenience wrapper for from_structured with JSON format and auto-detection.
+
+    Auto-detects CloudEvents version (v0.3 or v1.0) from body.
 
     Example:
         >>> from cloudevents.core.bindings import http
         >>> event = http.from_structured_event(message)
 
     :param message: HTTPMessage to parse
     :param event_format: Format implementation (defaults to JSONFormat)
-    :return: CloudEvent instance
+    :return: CloudEvent instance (v0.3 or v1.0 based on specversion)
     """
     if event_format is None:
         event_format = JSONFormat()
-    return from_structured(message, event_format, CloudEvent)
+    return from_structured(message, event_format, None)
 
 
 def from_http_event(
     message: HTTPMessage,
     event_format: Format | None = None,
-) -> CloudEvent:
+) -> BaseCloudEvent:
     """
-    Convenience wrapper for from_http with JSON format and CloudEvent as defaults.
-    Auto-detects binary or structured mode.
+    Convenience wrapper for from_http with JSON format and auto-detection.
+    Auto-detects binary or structured mode, and CloudEvents version.
 
     Example:
         >>> from cloudevents.core.bindings import http
         >>> event = http.from_http_event(message)
 
     :param message: HTTPMessage to parse
     :param event_format: Format implementation (defaults to JSONFormat)
-    :return: CloudEvent instance
+    :return: CloudEvent instance (v0.3 or v1.0 based on specversion)
     """
     if event_format is None:
         event_format = JSONFormat()
-    return from_http(message, event_format, CloudEvent)
+    return from_http(message, event_format, None)