Improve timezone handling, db models convert naive/timezone-aware

src/ddns_service/__init__.py

@@ -10,26 +10,20 @@ import datetime
 __version__ = "1.0.0"
 __author__ = "Thomas Oettli <spacefreak@noop.ch>"
 
-# DynDNS-compatible response statuses
-STATUS_GOOD = "good"
-STATUS_NOCHG = "nochg"
-STATUS_BADAUTH = "badauth"
-STATUS_NOHOST = "nohost"
-STATUS_DNSERR = "dnserr"
-STATUS_ABUSE = "abuse"
-STATUS_BADIP = "badip"
-
 __all__ = [
     "app",
     "cleanup",
     "cli",
     "config",
+    "datetime_aware_utc",
+    "datetime_naive_utc",
     "datetime_str",
     "dns",
     "email",
     "logging",
     "main",
     "models",
+    "now_utc"
     "ratelimit",
     "server",
     "STATUS_GOOD",
@@ -41,13 +35,75 @@ __all__ = [
     "STATUS_BADIP",
 ]
 
+# DynDNS-compatible response statuses
+STATUS_GOOD = "good"
+STATUS_NOCHG = "nochg"
+STATUS_BADAUTH = "badauth"
+STATUS_NOHOST = "nohost"
+STATUS_DNSERR = "dnserr"
+STATUS_ABUSE = "abuse"
+STATUS_BADIP = "badip"
+
 DATETIME_FORMAT = "%Y-%m-%d %H:%M:%S %Z"
 
 # Datetime convention:
-# All datetime objects in this codebase are naive UTC to match database storage.
-# - utc_now(): returns naive UTC datetime
-# - datetime_str(): converts naive UTC to display string (adds tzinfo for formatting)
+# All datetime objects in this codebase are timezone-aware.
+# - now_utc(): returns timezone-aware UTC datetime
+# - datetime_str(): converts naive UTC (adds tzinfo for formatting)
+#   or timezone-aware datetime to display string
 # - Database stores/returns naive datetimes (always UTC by convention)
+# - Database models automatically convert between naive/timezone-aware datetimes
+
+
+def now_utc():
+    """
+    Get current date and time in UTC.
+
+    Returns:
+        Timezone-aware datetime object in UTC.
+    """
+    return datetime.datetime.now(datetime.UTC)
+
+
+def datetime_naive_utc(dt):
+    """
+    Convert datetime to naive UTC datetime.
+
+    Args:
+        dt: Datetime object (naive UTC or timezone-aware or None).
+
+    Returns:
+        Naive datetime object in UTC or None if dt is not a datetime.
+    """
+    if not isinstance(dt, datetime.datetime):
+        return None
+
+    if not dt.tzinfo:
+        return dt
+
+    return dt.astimezone(datetime.UTC).replace(tzinfo=None)
+
+
+def datetime_aware_utc(dt):
+    """
+    Convert datetime to UTC datetime.
+
+    Args:
+        dt: Datetime object (naive UTC or timezone-aware or None).
+
+    Returns:
+        Timzone-aware datetime object in UTC or None if dt is not a datetime.
+    """
+    if not isinstance(dt, datetime.datetime):
+        return None
+
+    if not dt.tzinfo:
+        return dt.replace(tzinfo=datetime.UTC)
+
+    if dt.tzinfo == datetime.UTC:
+        return dt
+
+    return dt.astimezone(datetime.UTC)
 
 
 def datetime_str(dt, utc=False):
@@ -72,13 +128,3 @@ def datetime_str(dt, utc=False):
         return aware_dt.strftime(DATETIME_FORMAT)
     else:
         return aware_dt.astimezone().strftime(DATETIME_FORMAT)
-
-
-def utc_now():
-    """
-    Get current time as naive UTC datetime.
-
-    Returns naive datetime to match database storage behavior.
-    All naive datetimes in this codebase are assumed to be UTC.
-    """
-    return datetime.datetime.now(datetime.UTC).replace(tzinfo=None)