chore: add default values for id, time and specversion (#264)

* chore: add default values for `id`, `time` and `specversion`

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

* Update MIGRATION.md

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

* chore: update docstrings

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

---------

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

Author: PlugaruT

MIGRATION.md

@@ -15,7 +15,7 @@ v2 is a ground-up rewrite with four fundamental shifts:
 
 1. **Protocol-based design** -- `BaseCloudEvent` is a `Protocol`, not a base class. Events expose explicit getter methods instead of dict-like access.
 2. **Explicit serialization** -- Implicit JSON handling with marshaller callbacks is replaced by a `Format` protocol. `JSONFormat` is the built-in implementation; you can write your own.
-3. **No auto-generated attributes** -- v1 auto-generated `id` (UUID), `time` (UTC now), and `specversion` ("1.0") if omitted. v2 requires all required attributes to be provided explicitly.
+3. **Same auto-generated attributes** -- Like v1, v2 auto-generates `id` (UUID4), `time` (UTC now), and `specversion` (`"1.0"` or `"0.3"`) if omitted. Only `type` and `source` are strictly required.
 4. **Strict validation** -- Events are validated at construction time. Extension attribute names must be 1-20 lowercase alphanumeric characters. `time` must be a timezone-aware `datetime`.
 
 ## Creating Events
@@ -35,18 +35,11 @@ event = CloudEvent(
 **v2:**
 
 ```python
-import uuid
 from cloudevents.core.v1.event import CloudEvent
 
-# All required attributes must be explicit
+# id, specversion, and time are auto-generated (just like v1)
 event = CloudEvent(
-    attributes={
-        "type": "com.example.test",
-        "source": "/myapp",
-        "id": str(uuid.uuid4()),
-        "specversion": "1.0",
-        # "time" is optional and NOT auto-generated
-    },
+    attributes={"type": "com.example.test", "source": "/myapp"},
     data={"message": "Hello"},
 )
 ```
@@ -326,7 +319,7 @@ from cloudevents.core.exceptions import (
 
 ```python
 try:
-    event = CloudEvent(attributes={"source": "/test"})  # missing type, id, specversion
+    event = CloudEvent(attributes={"source": "/test"})  # missing type
 except CloudEventValidationError as e:
     # e.errors is a dict[str, list[BaseCloudEventException]]
     for attr_name, errors in e.errors.items():
@@ -339,9 +332,6 @@ except CloudEventValidationError as e:
 |---|---|---|
 | Pydantic integration | `from cloudevents.pydantic import CloudEvent` | Removed -- use the core `CloudEvent` directly |
 | Dict-like event access | `event["source"]`, `event["x"] = y` | `event.get_source()`, `event.get_extension("x")` |
-| Auto-generated `id` | Automatic UUID4 | Provide explicitly |
-| Auto-generated `time` | Automatic UTC timestamp | Provide explicitly or omit |
-| Auto-generated `specversion` | Defaults to `"1.0"` | Provide explicitly |
 | `from_dict()` | `from cloudevents.http import from_dict` | Construct `CloudEvent(attributes=d)` directly |
 | `to_dict()` | `from cloudevents.conversion import to_dict` | `event.get_attributes()` + `event.get_data()` |
 | `from_json()` | `from cloudevents.http import from_json` | `JSONFormat().read(None, json_bytes)` |

src/cloudevents/core/v03/event.py

@@ -13,8 +13,9 @@
 #    under the License.
 
 import re
+import uuid
 from collections import defaultdict
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Any, Final
 
 from cloudevents.core.base import BaseCloudEvent
@@ -52,13 +53,20 @@ def __init__(
         data: dict[str, Any] | str | bytes | None = None,
     ) -> None:
         """
-        Create a new CloudEvent v0.3 instance.
-
         :param attributes: The attributes of the CloudEvent instance.
+            If not provided, ``specversion`` defaults to ``"0.3"``,
+            ``id`` to a UUID4, and ``time`` to the current UTC timestamp.
         :param data: The payload of the CloudEvent instance.
-
-        :raises CloudEventValidationError: If any of the required attributes are missing or have invalid values.
+        :raises CloudEventValidationError: If any of the required attributes
+            are missing or have invalid values.
         """
+        if "specversion" not in attributes:
+            attributes["specversion"] = SPECVERSION_V0_3
+        if "id" not in attributes:
+            attributes["id"] = str(uuid.uuid4())
+        if "time" not in attributes:
+            attributes["time"] = datetime.now(timezone.utc)
+
         self._validate_attribute(attributes=attributes)
         self._attributes: dict[str, Any] = attributes
         self._data: dict[str, Any] | str | bytes | None = data

src/cloudevents/core/v1/event.py

@@ -13,8 +13,9 @@
 #    under the License.
 
 import re
+import uuid
 from collections import defaultdict
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Any, Final
 
 from cloudevents.core.base import BaseCloudEvent
@@ -38,11 +39,33 @@
 
 
 class CloudEvent(BaseCloudEvent):
+    """
+    CloudEvents v1.0 implementation.
+
+    This class represents a CloudEvent conforming to the v1.0 specification.
+    See https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md for details.
+    """
+
     def __init__(
         self,
         attributes: dict[str, Any],
         data: dict[str, Any] | str | bytes | None = None,
     ) -> None:
+        """
+        :param attributes: The attributes of the CloudEvent instance.
+            If not provided, ``specversion`` defaults to ``"1.0"``,
+            ``id`` to a UUID4, and ``time`` to the current UTC timestamp.
+        :param data: The payload of the CloudEvent instance.
+        :raises CloudEventValidationError: If any of the required attributes
+            are missing or have invalid values.
+        """
+        if "specversion" not in attributes:
+            attributes["specversion"] = SPECVERSION_V1_0
+        if "id" not in attributes:
+            attributes["id"] = str(uuid.uuid4())
+        if "time" not in attributes:
+            attributes["time"] = datetime.now(timezone.utc)
+
         self._validate_attribute(attributes=attributes)
         self._attributes: dict[str, Any] = attributes
         self._data: dict[str, Any] | str | bytes | None = data

tests/test_core/test_v03/test_event.py

@@ -32,11 +32,6 @@ def test_missing_required_attributes() -> None:
         CloudEvent({})
 
     expected_errors = {
-        "id": [
-            str(MissingRequiredAttributeError("id")),
-            str(InvalidAttributeValueError("id", "Attribute 'id' must not be None")),
-            str(InvalidAttributeTypeError("id", str)),
-        ],
         "source": [
             str(MissingRequiredAttributeError("source")),
             str(InvalidAttributeTypeError("source", str)),
@@ -45,15 +40,6 @@ def test_missing_required_attributes() -> None:
             str(MissingRequiredAttributeError("type")),
             str(InvalidAttributeTypeError("type", str)),
         ],
-        "specversion": [
-            str(MissingRequiredAttributeError("specversion")),
-            str(InvalidAttributeTypeError("specversion", str)),
-            str(
-                InvalidAttributeValueError(
-                    "specversion", "Attribute 'specversion' must be '0.3'"
-                )
-            ),
-        ],
     }
 
     actual_errors = {
@@ -358,6 +344,65 @@ def test_custom_extension(extension_name: str, expected_error: dict) -> None:
     assert actual_errors == expected_error
 
 
+def test_default_specversion() -> None:
+    event = CloudEvent(
+        attributes={"source": "/source", "type": "test", "id": "1"},
+    )
+    assert event.get_specversion() == "0.3"
+
+
+def test_default_id() -> None:
+    event = CloudEvent(
+        attributes={"source": "/source", "type": "test", "specversion": "0.3"},
+    )
+    assert isinstance(event.get_id(), str)
+    assert len(event.get_id()) == 36  # UUID4 format
+
+
+def test_default_id_is_unique() -> None:
+    event1 = CloudEvent(attributes={"source": "/s", "type": "t"})
+    event2 = CloudEvent(attributes={"source": "/s", "type": "t"})
+    assert event1.get_id() != event2.get_id()
+
+
+def test_default_time() -> None:
+    before = datetime.now(tz=timezone.utc)
+    event = CloudEvent(
+        attributes={"source": "/source", "type": "test", "specversion": "0.3"},
+    )
+    after = datetime.now(tz=timezone.utc)
+    assert event.get_time() is not None
+    assert before <= event.get_time() <= after
+    assert event.get_time().tzinfo is not None
+
+
+def test_explicit_values_override_defaults() -> None:
+    custom_time = datetime(2024, 6, 15, 12, 0, 0, tzinfo=timezone.utc)
+    event = CloudEvent(
+        attributes={
+            "source": "/source",
+            "type": "test",
+            "specversion": "0.3",
+            "id": "my-custom-id",
+            "time": custom_time,
+        },
+    )
+    assert event.get_id() == "my-custom-id"
+    assert event.get_time() == custom_time
+    assert event.get_specversion() == "0.3"
+
+
+def test_minimal_event_with_defaults() -> None:
+    event = CloudEvent(
+        attributes={"source": "/source", "type": "test"},
+    )
+    assert event.get_source() == "/source"
+    assert event.get_type() == "test"
+    assert event.get_specversion() == "0.3"
+    assert event.get_id() is not None
+    assert event.get_time() is not None
+
+
 def test_cloud_event_v03_constructor() -> None:
     """Test creating a v0.3 CloudEvent with all attributes"""
     id = "1"

tests/test_core/test_v1/test_event.py

@@ -32,11 +32,6 @@ def test_missing_required_attributes() -> None:
         CloudEvent({})
 
     expected_errors = {
-        "id": [
-            str(MissingRequiredAttributeError("id")),
-            str(InvalidAttributeValueError("id", "Attribute 'id' must not be None")),
-            str(InvalidAttributeTypeError("id", str)),
-        ],
         "source": [
             str(MissingRequiredAttributeError("source")),
             str(InvalidAttributeTypeError("source", str)),
@@ -45,15 +40,6 @@ def test_missing_required_attributes() -> None:
             str(MissingRequiredAttributeError("type")),
             str(InvalidAttributeTypeError("type", str)),
         ],
-        "specversion": [
-            str(MissingRequiredAttributeError("specversion")),
-            str(InvalidAttributeTypeError("specversion", str)),
-            str(
-                InvalidAttributeValueError(
-                    "specversion", "Attribute 'specversion' must be '1.0'"
-                )
-            ),
-        ],
     }
 
     actual_errors = {
@@ -294,6 +280,65 @@ def test_custom_extension(extension_name: str, expected_error: dict) -> None:
     assert actual_errors == expected_error
 
 
+def test_default_specversion() -> None:
+    event = CloudEvent(
+        attributes={"source": "/source", "type": "test", "id": "1"},
+    )
+    assert event.get_specversion() == "1.0"
+
+
+def test_default_id() -> None:
+    event = CloudEvent(
+        attributes={"source": "/source", "type": "test", "specversion": "1.0"},
+    )
+    assert isinstance(event.get_id(), str)
+    assert len(event.get_id()) == 36  # UUID4 format
+
+
+def test_default_id_is_unique() -> None:
+    event1 = CloudEvent(attributes={"source": "/s", "type": "t"})
+    event2 = CloudEvent(attributes={"source": "/s", "type": "t"})
+    assert event1.get_id() != event2.get_id()
+
+
+def test_default_time() -> None:
+    before = datetime.now(tz=timezone.utc)
+    event = CloudEvent(
+        attributes={"source": "/source", "type": "test", "specversion": "1.0"},
+    )
+    after = datetime.now(tz=timezone.utc)
+    assert event.get_time() is not None
+    assert before <= event.get_time() <= after
+    assert event.get_time().tzinfo is not None
+
+
+def test_explicit_values_override_defaults() -> None:
+    custom_time = datetime(2024, 6, 15, 12, 0, 0, tzinfo=timezone.utc)
+    event = CloudEvent(
+        attributes={
+            "source": "/source",
+            "type": "test",
+            "specversion": "1.0",
+            "id": "my-custom-id",
+            "time": custom_time,
+        },
+    )
+    assert event.get_id() == "my-custom-id"
+    assert event.get_time() == custom_time
+    assert event.get_specversion() == "1.0"
+
+
+def test_minimal_event_with_defaults() -> None:
+    event = CloudEvent(
+        attributes={"source": "/source", "type": "test"},
+    )
+    assert event.get_source() == "/source"
+    assert event.get_type() == "test"
+    assert event.get_specversion() == "1.0"
+    assert event.get_id() is not None
+    assert event.get_time() is not None
+
+
 def test_cloud_event_constructor() -> None:
     id = "1"
     source = "/source"