Rework datetime handling

To properly convert from protobuf to datetime, one has to explicitly
handle the nanoseconds like so:

```python
    # Add microseconds and add nanoseconds converted to microseconds
    microseconds = int(ts.nanos / 1000)
    return datetime.fromtimestamp(ts.seconds + microseconds * 1e-6,
tz=tz)
```

We implemented a convert function that does exactly this, but we have
not been using it consistently yet. This commit replaces the last
occurances.

With that in mind, this commit changes:
* Consistently use the conversion function from the common repository
Fix start_time conversion imprecision bug
* Use shorter notations to set timezones
* Raise on invalid timezone in create()

Signed-off-by: Mathias L. Baumann <[email protected]>

Author: Marenz

src/frequenz/client/dispatch/_client.py

@@ -19,7 +19,8 @@
 from frequenz.api.dispatch.v1.dispatch_pb2 import (
     TimeIntervalFilter as PBTimeIntervalFilter,
 )
-from google.protobuf.timestamp_pb2 import Timestamp
+
+from frequenz.client.base.conversion import to_timestamp
 
 from ._internal_types import DispatchCreateRequest
 from .types import (
@@ -86,14 +87,6 @@ async def list(
         """
         time_interval = None
 
-        def to_timestamp(dt: datetime | None) -> Timestamp | None:
-            if dt is None:
-                return None
-
-            ts = Timestamp()
-            ts.FromDatetime(dt)
-            return ts
-
         if start_from or start_to or end_from or end_to:
             time_interval = PBTimeIntervalFilter(
                 start_from=to_timestamp(start_from),
@@ -147,9 +140,13 @@ async def create(
         Raises:
             ValueError: If start_time is in the past.
         """
-        if start_time <= datetime.now().astimezone(start_time.tzinfo):
+        if start_time <= datetime.now(tz=start_time.tzinfo):
             raise ValueError("start_time must not be in the past")
 
+        # Raise if it's not UTC
+        if start_time.tzinfo is None or start_time.tzinfo.utcoffset(start_time) is None:
+            raise ValueError("start_time must be timezone aware")
+
         request = DispatchCreateRequest(
             microgrid_id=microgrid_id,
             type=_type,
@@ -195,7 +192,7 @@ async def update(
                 case "type":
                     raise ValueError("Updating type is not supported")
                 case "start_time":
-                    msg.update.start_time.FromDatetime(val)
+                    msg.update.start_time.CopyFrom(to_timestamp(val))
                 case "duration":
                     msg.update.duration = int(val.total_seconds())
                 case "selector":

src/frequenz/client/dispatch/_internal_types.py

@@ -5,7 +5,7 @@
 
 
 from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
+from datetime import datetime, timedelta
 from typing import Any
 
 # pylint: disable=no-name-in-module
@@ -16,6 +16,8 @@
 # pylint: enable=no-name-in-module
 from google.protobuf.json_format import MessageToDict
 
+from frequenz.client.base.conversion import to_datetime, to_timestamp
+
 from .types import (
     ComponentSelector,
     RecurrenceRule,
@@ -79,7 +81,7 @@ def from_protobuf(
         return DispatchCreateRequest(
             microgrid_id=pb_object.microgrid_id,
             type=pb_object.type,
-            start_time=pb_object.start_time.ToDatetime().replace(tzinfo=timezone.utc),
+            start_time=to_datetime(pb_object.start_time),
             duration=timedelta(seconds=pb_object.duration),
             selector=component_selector_from_protobuf(pb_object.selector),
             is_active=pb_object.is_active,
@@ -98,7 +100,7 @@ def to_protobuf(self) -> PBDispatchCreateRequest:
 
         pb_request.microgrid_id = self.microgrid_id
         pb_request.type = self.type
-        pb_request.start_time.FromDatetime(self.start_time)
+        pb_request.start_time.CopyFrom(to_timestamp(self.start_time))
         pb_request.duration = int(self.duration.total_seconds())
         pb_request.selector.CopyFrom(component_selector_to_protobuf(self.selector))
         pb_request.is_active = self.is_active

src/frequenz/client/dispatch/types.py

@@ -5,7 +5,7 @@
 
 
 from dataclasses import dataclass, field
-from datetime import datetime, timedelta, timezone
+from datetime import datetime, timedelta
 from enum import IntEnum
 from typing import Any
 
@@ -17,6 +17,8 @@
 from frequenz.api.dispatch.v1.dispatch_pb2 import RecurrenceRule as PBRecurrenceRule
 from google.protobuf.json_format import MessageToDict
 
+from frequenz.client.base.conversion import to_datetime, to_timestamp
+
 # pylint: enable=no-name-in-module
 from frequenz.client.common.microgrid.components import ComponentCategory
 
@@ -125,10 +127,7 @@ def from_protobuf(cls, pb_criteria: PBRecurrenceRule.EndCriteria) -> "EndCriteri
             case "count":
                 instance.count = pb_criteria.count
             case "until":
-                instance.until = pb_criteria.until.ToDatetime().replace(
-                    tzinfo=timezone.utc
-                )
-
+                instance.until = to_datetime(pb_criteria.until)
         return instance
 
     def to_protobuf(self) -> PBRecurrenceRule.EndCriteria:
@@ -142,7 +141,7 @@ def to_protobuf(self) -> PBRecurrenceRule.EndCriteria:
         if self.count is not None:
             pb_criteria.count = self.count
         elif self.until is not None:
-            pb_criteria.until.FromDatetime(self.until)
+            pb_criteria.until.CopyFrom(to_timestamp(self.until))
 
         return pb_criteria
 
@@ -306,9 +305,9 @@ def from_protobuf(cls, pb_object: PBDispatch) -> "Dispatch":
             id=pb_object.id,
             microgrid_id=pb_object.microgrid_id,
             type=pb_object.type,
-            create_time=pb_object.create_time.ToDatetime().replace(tzinfo=timezone.utc),
-            update_time=pb_object.update_time.ToDatetime().replace(tzinfo=timezone.utc),
-            start_time=pb_object.start_time.ToDatetime().replace(tzinfo=timezone.utc),
+            create_time=to_datetime(pb_object.create_time),
+            update_time=to_datetime(pb_object.update_time),
+            start_time=to_datetime(pb_object.start_time),
             duration=timedelta(seconds=pb_object.duration),
             selector=component_selector_from_protobuf(pb_object.selector),
             active=pb_object.is_active,
@@ -328,9 +327,9 @@ def to_protobuf(self) -> PBDispatch:
         pb_dispatch.id = self.id
         pb_dispatch.microgrid_id = self.microgrid_id
         pb_dispatch.type = self.type
-        pb_dispatch.create_time.FromDatetime(self.create_time)
-        pb_dispatch.update_time.FromDatetime(self.update_time)
-        pb_dispatch.start_time.FromDatetime(self.start_time)
+        pb_dispatch.create_time.CopyFrom(to_timestamp(self.create_time))
+        pb_dispatch.update_time.CopyFrom(to_timestamp(self.update_time))
+        pb_dispatch.start_time.CopyFrom(to_timestamp(self.start_time))
         pb_dispatch.duration = int(self.duration.total_seconds())
         pb_dispatch.selector.CopyFrom(component_selector_to_protobuf(self.selector))
         pb_dispatch.is_active = self.active