fix(services/util): Mv normalize_datetime_to_utc() to services/util & used it in well_inventory

Author: TylerAdamMartinez

schemas/water_level_csv.py

@@ -15,7 +15,7 @@
 # ===============================================================================
 from __future__ import annotations
 
-from datetime import datetime, timezone
+from datetime import datetime
 from typing import Annotated
 
 from core.enums import DataQuality, GroundwaterLevelReason, SampleMethod
@@ -29,7 +29,7 @@
 )
 from pydantic.functional_validators import BeforeValidator
 
-from services.util import convert_dt_tz_naive_to_tz_aware
+from services.util import normalize_datetime_to_utc
 
 WATER_LEVEL_REQUIRED_FIELDS = [
     "well_name_point_id",
@@ -84,18 +84,6 @@ def empty_str_to_none(value):
 OptionalFloat = Annotated[float | None, BeforeValidator(empty_str_to_none)]
 
 
-def _normalize_datetime_to_utc(value: datetime | str) -> datetime:
-    if isinstance(value, str):
-        value = datetime.fromisoformat(value)
-    elif not isinstance(value, datetime):
-        raise ValueError("value must be a datetime or ISO format string")
-
-    if value.tzinfo is None:
-        value = convert_dt_tz_naive_to_tz_aware(value, "America/Denver")
-
-    return value.astimezone(timezone.utc)
-
-
 def _canonicalize_enum_value(
     value: str | None, enum_cls, field_name: str
 ) -> str | None:
@@ -182,7 +170,7 @@ def normalize_sample_method(cls, value: str) -> str:
     )
     @classmethod
     def normalize_datetime_field(cls, value: datetime | str) -> datetime:
-        return _normalize_datetime_to_utc(value)
+        return normalize_datetime_to_utc(value)
 
     @field_validator("depth_to_water_ft")
     @classmethod

schemas/well_inventory.py

@@ -48,8 +48,7 @@
     AliasChoices,
 )
 from schemas import past_or_today_validator, PastOrTodayDatetime
-from services.util import convert_dt_tz_naive_to_tz_aware
-
+from services.util import normalize_datetime_to_utc
 
 def empty_str_to_none(v):
     if isinstance(v, str) and v.strip() == "":
@@ -362,19 +361,16 @@ def normalize_complete_monitoring_frequency(cls, data):
         return data
 
     @field_validator("date_time", mode="before")
+    @classmethod
     def make_date_time_tz_aware(cls, v):
-        if isinstance(v, str):
-            dt = datetime.fromisoformat(v)
-        elif isinstance(v, datetime):
-            dt = v
-        else:
-            raise ValueError("date_time must be a datetime or ISO format string")
-
-        if dt.tzinfo is None:
-            aware_dt = convert_dt_tz_naive_to_tz_aware(dt, "America/Denver")
-            return aware_dt
-        else:
-            raise ValueError("date_time must be a timezone-naive datetime")
+        normalize_datetime_to_utc(v)
+
+    @field_validator("measurement_date_time", mode="before")
+    @classmethod
+    def normalize_measurement_date_time(cls, v):
+        if v is None or (isinstance(v, str) and v.strip() == ""):
+            return None
+        return normalize_datetime_to_utc(v)
 
     @model_validator(mode="after")
     def validate_model(self):

services/util.py

@@ -64,6 +64,25 @@ def transform_srid(geometry, source_srid, target_srid):
     return transform(transformer.transform, geometry)
 
 
+def normalize_datetime_to_utc(value: datetime | str) -> datetime:
+    dt: datetime
+    
+    if isinstance(value, str):
+        dt = datetime.fromisoformat(value)
+    elif isinstance(value, datetime):
+        dt = value
+    else:
+        raise ValueError("value must be a datetime or ISO format string")
+
+    # Treat the datetime as "naive" if it has no tzinfo OR its tzinfo does not
+    # provide a valid UTC offset (utcoffset() returns None). Some tzinfo
+    # implementations can be attached but still behave like naive datetimes,
+    # so we handle both cases before assigning a default timezone.
+    if dt.tzinfo is None or dt.utcoffset() is None:
+        dt = convert_dt_tz_naive_to_tz_aware(dt, "America/Denver")
+
+    return dt.astimezone(timezone.utc)
+
 def convert_dt_tz_naive_to_tz_aware(
     dt_naive: datetime,
     iana_timezone: str = "America/Denver",
@@ -156,7 +175,7 @@ def get_county_from_point(lon: float, lat: float) -> str | None:
         return attrs["BASENAME"]
 
 
-def get_quad_name_from_point(lon: float, lat: float) -> str:
+def get_quad_name_from_point(lon: float, lat: float) -> str | None:
     url = "https://carto.nationalmap.gov/arcgis/rest/services/map_indices/MapServer/10/query"
     params = {
         "f": "json",