From 490004f66a4831bc3170061e5bfd3844313bf14a Mon Sep 17 00:00:00 2001
From: Federico Busetti <729029+febus982@users.noreply.github.com>
Date: Thu, 26 Sep 2024 20:39:48 +0100
Subject: [PATCH] Add docstrings to CloudEvent factory and field types

Signed-off-by: Federico Busetti <729029+febus982@users.noreply.github.com>
---
 cloudevents_pydantic/events/_event.py         | 19 ++++++++++--
 .../events/field_types/_canonic_types.py      | 30 +++++++++++++++++--
 2 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/cloudevents_pydantic/events/_event.py b/cloudevents_pydantic/events/_event.py
index 073aec6..48832eb 100644
--- a/cloudevents_pydantic/events/_event.py
+++ b/cloudevents_pydantic/events/_event.py
@@ -23,6 +23,7 @@
 import base64
 import datetime
 import typing
+from typing import Union
 
 from cloudevents.pydantic.fields_docs import FIELD_DESCRIPTIONS
 from pydantic import (
@@ -36,7 +37,8 @@
 from ulid import ULID
 
 from .field_types import URI, DateTime, SpecVersion, String, URIReference
-from .field_types._canonic_types import DEFAULT_SPECVERSION
+
+DEFAULT_SPECVERSION = SpecVersion.v1_0
 
 
 class CloudEvent(BaseModel):  # type: ignore
@@ -49,9 +51,22 @@ def event_factory(
         cls,
         id: typing.Optional[str] = None,
         specversion: typing.Optional[SpecVersion] = None,
-        time: typing.Optional[datetime.datetime] = None,
+        time: typing.Optional[Union[datetime.datetime, str]] = None,
         **kwargs,
     ) -> "CloudEvent":
+        """
+        Builds a new CloudEvent using sensible defaults.
+
+        :param id: The event id, defaults to a ULID
+        :type id: typing.Optional[str]
+        :param specversion: The specversion of the event, defaults to 1.0
+        :type specversion: typing.Optional[SpecVersion]
+        :param time: The time the event occurred, defaults to now
+        :type time: typing.Optional[Union[datetime.datetime, str]]
+        :param kwargs: Other kwargs forwarded directly to the CloudEvent model.
+        :return: A new CloudEvent model
+        :rtype: CloudEvent
+        """
         return cls(
             id=id or str(ULID()),
             specversion=specversion or DEFAULT_SPECVERSION,
diff --git a/cloudevents_pydantic/events/field_types/_canonic_types.py b/cloudevents_pydantic/events/field_types/_canonic_types.py
index 1553631..1300129 100644
--- a/cloudevents_pydantic/events/field_types/_canonic_types.py
+++ b/cloudevents_pydantic/events/field_types/_canonic_types.py
@@ -84,17 +84,44 @@ def generic_uri_validator(value: str) -> ParseResult:
 
 # TODO: Add types docstrings
 Boolean = Annotated[bool, PlainSerializer(bool_serializer)]
+"""
+A boolean value of "true" or "false"
+"""
+
 Integer = Annotated[int, Ge(-2147483648), Le(2147483648)]
+"""
+A whole number in the range -2,147,483,648 to +2,147,483,647 inclusive
+"""
+
 String = Annotated[str, StringConstraints(pattern=str_constraint)]
+"""
+Sequence of allowable Unicode characters
+"""
+
 # bytearray is coerced to bytes, memoryview is not supported
 Binary = Annotated[bytes, PlainSerializer(binary_serializer)]
+"""
+Sequence of bytes supporting base64 serialization/deserialization
+"""
+
 URI = Annotated[
     ParseResult, PlainValidator(absolute_uri_validator), PlainSerializer(url_serializer)
 ]
+"""
+Absolute uniform resource identifier
+"""
+
 URIReference = Annotated[
     ParseResult, PlainValidator(generic_uri_validator), PlainSerializer(url_serializer)
 ]
+"""
+Uniform resource identifier reference
+"""
+
 DateTime = datetime
+"""
+Date and time expression using the Gregorian Calendar
+"""
 
 
 class SpecVersion(str, Enum):
@@ -109,6 +136,3 @@ class SpecVersion(str, Enum):
 
     # v0_3 = "0.3"
     v1_0 = "1.0"
-
-
-DEFAULT_SPECVERSION = SpecVersion.v1_0