Field annotation composition

benchmark.py

@@ -41,7 +41,7 @@
 
 from cloudevents_pydantic.bindings.http import HTTPHandler
 from cloudevents_pydantic.events import CloudEvent
-from cloudevents_pydantic.events.field_types import Binary
+from cloudevents_pydantic.events.fields.types import Binary
 
 valid_json = '{"data_base64":"dGVzdA==","source":"https://example.com/event-producer","id":"b96267e2-87be-4f7a-b87c-82f64360d954","type":"com.example.string","specversion":"1.0","time":"2022-07-16T12:03:20.519216+04:00","subject":null,"datacontenttype":null,"dataschema":null}'
 test_iterations = 1000000

cloudevents_pydantic/events/_event.py

@@ -22,9 +22,8 @@
 # ==============================================================================
 import base64
 import datetime
-from typing import Any, Dict, Optional, Union
+from typing import Annotated, Any, Dict, Optional, Union
 
-from cloudevents.pydantic.fields_docs import FIELD_DESCRIPTIONS
 from pydantic import (
     BaseModel,
     ConfigDict,
@@ -36,7 +35,18 @@
 from pydantic_core.core_schema import ValidationInfo
 from ulid import ULID
 
-from .field_types import URI, Binary, DateTime, SpecVersion, String, URIReference
+from .fields.metadata import (
+    FieldData,
+    FieldDataContentType,
+    FieldDataSchema,
+    FieldId,
+    FieldSource,
+    FieldSpecVersion,
+    FieldSubject,
+    FieldTime,
+    FieldType,
+)
+from .fields.types import URI, Binary, DateTime, SpecVersion, String, URIReference
 
 DEFAULT_SPECVERSION = SpecVersion.v1_0
 
@@ -77,60 +87,21 @@ def event_factory(
             **kwargs,
         )
 
-    data: Any = Field(
-        title=FIELD_DESCRIPTIONS["data"].get("title"),
-        description=FIELD_DESCRIPTIONS["data"].get("description"),
-        examples=[FIELD_DESCRIPTIONS["data"].get("example")],
-        default=None,
-    )
+    data: Annotated[Any, Field(default=None), FieldData]
 
     # Mandatory fields
-    source: URIReference = Field(
-        title=FIELD_DESCRIPTIONS["source"].get("title"),
-        description=FIELD_DESCRIPTIONS["source"].get("description"),
-        examples=[FIELD_DESCRIPTIONS["source"].get("example")],
-    )
-    id: String = Field(
-        title=FIELD_DESCRIPTIONS["id"].get("title"),
-        description=FIELD_DESCRIPTIONS["id"].get("description"),
-        examples=[FIELD_DESCRIPTIONS["id"].get("example")],
-    )
-    type: String = Field(
-        title=FIELD_DESCRIPTIONS["type"].get("title"),
-        description=FIELD_DESCRIPTIONS["type"].get("description"),
-        examples=[FIELD_DESCRIPTIONS["type"].get("example")],
-    )
-    specversion: SpecVersion = Field(
-        title=FIELD_DESCRIPTIONS["specversion"].get("title"),
-        description=FIELD_DESCRIPTIONS["specversion"].get("description"),
-        examples=[FIELD_DESCRIPTIONS["specversion"].get("example")],
-    )
+    source: Annotated[URIReference, FieldSource]
+    id: Annotated[String, FieldId]
+    type: Annotated[String, FieldType]
+    specversion: Annotated[SpecVersion, FieldSpecVersion]
 
     # Optional fields
-    time: Optional[DateTime] = Field(
-        title=FIELD_DESCRIPTIONS["time"].get("title"),
-        description=FIELD_DESCRIPTIONS["time"].get("description"),
-        examples=[FIELD_DESCRIPTIONS["time"].get("example")],
-        default=None,
-    )
-    subject: Optional[String] = Field(
-        title=FIELD_DESCRIPTIONS["subject"].get("title"),
-        description=FIELD_DESCRIPTIONS["subject"].get("description"),
-        examples=[FIELD_DESCRIPTIONS["subject"].get("example")],
-        default=None,
-    )
-    datacontenttype: Optional[String] = Field(
-        title=FIELD_DESCRIPTIONS["datacontenttype"].get("title"),
-        description=FIELD_DESCRIPTIONS["datacontenttype"].get("description"),
-        examples=[FIELD_DESCRIPTIONS["datacontenttype"].get("example")],
-        default=None,
-    )
-    dataschema: Optional[URI] = Field(
-        title=FIELD_DESCRIPTIONS["dataschema"].get("title"),
-        description=FIELD_DESCRIPTIONS["dataschema"].get("description"),
-        examples=[FIELD_DESCRIPTIONS["dataschema"].get("example")],
-        default=None,
-    )
+    time: Annotated[Optional[DateTime], Field(default=None), FieldTime]
+    subject: Annotated[Optional[String], Field(default=None), FieldSubject]
+    datacontenttype: Annotated[
+        Optional[String], Field(default=None), FieldDataContentType
+    ]
+    dataschema: Annotated[Optional[URI], Field(default=None), FieldDataSchema]
 
     model_config = ConfigDict(
         extra="forbid",

cloudevents_pydantic/events/fields/__init__.py

@@ -0,0 +1,23 @@
+# ==============================================================================
+#  Copyright (c) 2024 Federico Busetti                                         =
+#  <729029+febus982@users.noreply.github.com>                                  =
+#                                                                              =
+#  Permission is hereby granted, free of charge, to any person obtaining a     =
+#  copy of this software and associated documentation files (the "Software"),  =
+#  to deal in the Software without restriction, including without limitation   =
+#  the rights to use, copy, modify, merge, publish, distribute, sublicense,    =
+#  and/or sell copies of the Software, and to permit persons to whom the       =
+#  Software is furnished to do so, subject to the following conditions:        =
+#                                                                              =
+#  The above copyright notice and this permission notice shall be included in  =
+#  all copies or substantial portions of the Software.                         =
+#                                                                              =
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  =
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,    =
+#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL     =
+#  THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  =
+#  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING     =
+#  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER         =
+#  DEALINGS IN THE SOFTWARE.                                                   =
+# ==============================================================================
+

cloudevents_pydantic/events/fields/metadata/__init__.py

@@ -0,0 +1,33 @@
+# ==============================================================================
+#  Copyright (c) 2024 Federico Busetti                                         =
+#  <729029+febus982@users.noreply.github.com>                                  =
+#                                                                              =
+#  Permission is hereby granted, free of charge, to any person obtaining a     =
+#  copy of this software and associated documentation files (the "Software"),  =
+#  to deal in the Software without restriction, including without limitation   =
+#  the rights to use, copy, modify, merge, publish, distribute, sublicense,    =
+#  and/or sell copies of the Software, and to permit persons to whom the       =
+#  Software is furnished to do so, subject to the following conditions:        =
+#                                                                              =
+#  The above copyright notice and this permission notice shall be included in  =
+#  all copies or substantial portions of the Software.                         =
+#                                                                              =
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  =
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,    =
+#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL     =
+#  THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  =
+#  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING     =
+#  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER         =
+#  DEALINGS IN THE SOFTWARE.                                                   =
+# ==============================================================================
+from ._fields import (
+    FieldData,
+    FieldDataContentType,
+    FieldDataSchema,
+    FieldId,
+    FieldSource,
+    FieldSpecVersion,
+    FieldSubject,
+    FieldTime,
+    FieldType,
+)

cloudevents_pydantic/events/fields/metadata/_fields.py

@@ -0,0 +1,44 @@
+# ==============================================================================
+#  Copyright (c) 2024 Federico Busetti                                         =
+#  <729029+febus982@users.noreply.github.com>                                  =
+#                                                                              =
+#  Permission is hereby granted, free of charge, to any person obtaining a     =
+#  copy of this software and associated documentation files (the "Software"),  =
+#  to deal in the Software without restriction, including without limitation   =
+#  the rights to use, copy, modify, merge, publish, distribute, sublicense,    =
+#  and/or sell copies of the Software, and to permit persons to whom the       =
+#  Software is furnished to do so, subject to the following conditions:        =
+#                                                                              =
+#  The above copyright notice and this permission notice shall be included in  =
+#  all copies or substantial portions of the Software.                         =
+#                                                                              =
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  =
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,    =
+#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL     =
+#  THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  =
+#  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING     =
+#  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER         =
+#  DEALINGS IN THE SOFTWARE.                                                   =
+# ==============================================================================
+
+from cloudevents.pydantic.fields_docs import FIELD_DESCRIPTIONS
+from pydantic.fields import Field, FieldInfo
+
+
+def _ce_field_metadata(field_name: str) -> FieldInfo:
+    return Field(
+        title=FIELD_DESCRIPTIONS[field_name].get("title"),
+        description=FIELD_DESCRIPTIONS[field_name].get("description"),
+        examples=[FIELD_DESCRIPTIONS[field_name].get("example")],
+    )
+
+
+FieldData: FieldInfo = _ce_field_metadata("data")
+FieldSource: FieldInfo = _ce_field_metadata("source")
+FieldId: FieldInfo = _ce_field_metadata("id")
+FieldType: FieldInfo = _ce_field_metadata("type")
+FieldSpecVersion: FieldInfo = _ce_field_metadata("specversion")
+FieldTime: FieldInfo = _ce_field_metadata("time")
+FieldSubject: FieldInfo = _ce_field_metadata("subject")
+FieldDataContentType: FieldInfo = _ce_field_metadata("datacontenttype")
+FieldDataSchema: FieldInfo = _ce_field_metadata("dataschema")

docs/event_class.md

@@ -93,52 +93,54 @@ You can use either `str` values or python objects (see the `time` field)
 ///
 ///
 
-## Create your own event subclasses in the right way
+## Best practices when creating your event classes
 
 When you create event types in your app you will want to make sure to follow these best practices:
 
 * Use `TypedDict` for structured data instead of nested pydantic models (as specified in
   [Pydantic performance](https://docs.pydantic.dev/latest/concepts/performance/#use-typeddict-over-nested-models)
   documentatin)
-* Use the fields types defined in the `cloudevents_pydantic.events.field_types`. These types will
+* Use the fields types defined in the `cloudevents_pydantic.events.field.types`. These types will
   be kept up to date and make sure their validation, serialization and deserialization rules
   will be compliant with the [CloudEvents spec](https://github.com/cloudevents/spec/tree/main).
+* Write your own pydantic `Field` for data
+* Use the fields available in the `cloudevents_pydantic.events.field.metadata` when overriding
+  the cloudevent fields to inherit CloudEvents field descriptive metadata (i.e. title, description)
+  will be populated in the schema.
+
+Example:
 
-/// tab | class Syntax
 ```python
-from typing import TypedDict, Literal
-from cloudevents_pydantic.events import CloudEvent, field_types
+from typing import Annotated, Literal, TypedDict
+
+from pydantic import Field
+
+from cloudevents_pydantic.events import CloudEvent
+from cloudevents_pydantic.events.fields import metadata, types
+
 
 class OrderCreatedData(TypedDict):
-    a_str: field_types.String
-    an_int: field_types.Integer
+    a_str: types.String
+    an_int: types.Integer
 
-class OrderCreated(CloudEvent):
-    data: OrderCreatedData
-    type: Literal["order_created"] = "order_created"
-    source: field_types.String = "order_service"
 
-event = OrderCreated.event_factory(
-    data={"a_str": "a nice string", "an_int": 1},
+OrderCreatedDataField = Field(
+    title="An order representation",
+    description="A nice new order has been created! OMG!",
+    examples=["{'a_str': 'a nice string', 'an_int': 1}"],
 )
-```
-///
 
-/// tab | inline Syntax
-```python
-from typing import TypedDict, Literal
-from cloudevents_pydantic.events import CloudEvent, field_types
 
 class OrderCreated(CloudEvent):
-    data: TypedDict("OrderCreatedData", {"a_str": field_types.String, "an_int": field_types.Integer})
-    type: Literal["order_created"] = "order_created"
-    source: field_types.String = "order_service"
-
-event = OrderCreated.event_factory(
-    data={"a_str": "a nice string", "an_int": 1},
-)
+    data: Annotated[OrderCreatedData, OrderCreatedDataField]
+    type: Annotated[
+        Literal["order_created"], Field(default="order_created"), metadata.FieldType
+    ]
+    source: Annotated[
+        Literal["order_service"], Field(default="order_service"), metadata.FieldSource
+    ]
 ```
-///
+
 
 /// admonition | Use subclasses
     type: warning

tests/events/test__event.py

@@ -29,7 +29,7 @@
 from ulid import ULID
 
 from cloudevents_pydantic.events import CloudEvent
-from cloudevents_pydantic.events.field_types import SpecVersion
+from cloudevents_pydantic.events.fields.types import SpecVersion
 
 test_attributes = {
     "type": "com.example.string",

tests/events/test_field_types_serialization.py

@@ -25,7 +25,7 @@
 import pytest
 from pydantic import BaseModel
 
-from cloudevents_pydantic.events.field_types import (
+from cloudevents_pydantic.events.fields.types import (
     Binary,
     Boolean,
     URIReference,

tests/events/test_field_types_validation.py

@@ -27,7 +27,7 @@
 from typing_extensions import TypedDict
 
 from cloudevents_pydantic.events import CloudEvent
-from cloudevents_pydantic.events.field_types import (
+from cloudevents_pydantic.events.fields.types import (
     URI,
     Binary,
     Integer,

tests/formats/test_json.py

@@ -32,7 +32,7 @@
 from typing_extensions import TypedDict
 
 from cloudevents_pydantic.events import CloudEvent
-from cloudevents_pydantic.events.field_types import Binary, SpecVersion
+from cloudevents_pydantic.events.fields.types import Binary, SpecVersion
 from cloudevents_pydantic.formats.json import (
     from_json,
     from_json_batch,