fix: Return UTC-aware datetimes from unmarshalling (#809)

Previously, datetime fields were unmarshalled using datetime.fromtimestamp(value)
which returns a naive datetime in the server's local timezone. This caused:
- Non-deterministic behavior depending on server timezone
- Inability to compare retrieved datetimes with timezone-aware datetimes
- Time jumps around daylight savings transitions

This fix changes unmarshalling to use datetime.fromtimestamp(value, timezone.utc)
which returns a UTC-aware datetime. This follows the standard ORM pattern of
storing UTC and returning UTC-aware datetimes.

BREAKING CHANGE: Retrieved datetime fields are now UTC-aware instead of naive
local time. Code that compared retrieved datetimes with naive datetimes will
need to either:
1. Make the comparison datetime UTC-aware, or
2. Use .timestamp() for comparison

Fixes #807 (Return UTC-aware datetimes from unmarshalling)

* style: Format test file with ruff
* style: Format model.py with ruff
* fix: Make test use UTC-aware datetime after fix
* fix: preserve date round-trips across timezones
* chore: keep sync output formatter-clean in CI
* chore: align lint with current ruff rules
* fix: normalize date query timestamps to UTC

Author: abrookins

aredis_om/connections.py

@@ -2,6 +2,7 @@
 
 from . import redis
 
+
 URL = os.environ.get("REDIS_OM_URL", None)
 
 

aredis_om/model/encoders.py

@@ -33,6 +33,7 @@
 
 from pydantic import BaseModel
 
+
 try:
     from pydantic.deprecated.json import ENCODERS_BY_TYPE
     from pydantic_core import PydanticUndefined

aredis_om/model/migrations/__init__.py

@@ -18,6 +18,7 @@
     SchemaMigrator,
 )
 
+
 __all__ = [
     # Data migrations
     "BaseMigration",

aredis_om/model/migrations/data/__init__.py

@@ -8,4 +8,5 @@
 from .base import BaseMigration, DataMigrationError
 from .migrator import DataMigrator
 
+
 __all__ = ["BaseMigration", "DataMigrationError", "DataMigrator"]

aredis_om/model/migrations/data/base.py

@@ -9,6 +9,7 @@
 import time
 from typing import Any, Dict, List
 
+
 try:
     import psutil
 except ImportError:

aredis_om/model/migrations/data/builtin/__init__.py

@@ -11,4 +11,5 @@
     DatetimeFieldMigration,
 )
 
+
 __all__ = ["DatetimeFieldMigration", "DatetimeFieldDetector", "ConversionFailureMode"]

aredis_om/model/migrations/data/builtin/datetime_migration.py

@@ -16,6 +16,7 @@
 
 from ..base import BaseMigration, DataMigrationError
 
+
 log = logging.getLogger(__name__)
 
 
@@ -180,9 +181,9 @@ def __init__(self):
         self.converted_fields = 0
         self.skipped_fields = 0
         self.failed_conversions = 0
-        self.errors: List[Tuple[str, str, str, Exception]] = (
-            []
-        )  # (key, field, value, error)
+        self.errors: List[
+            Tuple[str, str, str, Exception]
+        ] = []  # (key, field, value, error)
 
     def add_conversion_error(self, key: str, field: str, value: Any, error: Exception):
         """Record a conversion error."""
@@ -393,7 +394,9 @@ async def save_progress(
         }
 
         await self.redis.set(
-            self.state_key, json.dumps(state_data), ex=86400  # Expire after 24 hours
+            self.state_key,
+            json.dumps(state_data),
+            ex=86400,  # Expire after 24 hours
         )
 
     async def load_progress(self) -> Dict[str, Any]:

aredis_om/model/migrations/schema/__init__.py

@@ -12,6 +12,7 @@
 from .legacy_migrator import MigrationAction, MigrationError, Migrator, SchemaDetector
 from .migrator import SchemaMigrator
 
+
 __all__ = [
     # Primary API
     "BaseSchemaMigration",

aredis_om/model/migrations/schema/legacy_migrator.py

@@ -18,6 +18,7 @@
 
 import redis
 
+
 log = logging.getLogger(__name__)
 
 
@@ -52,7 +53,8 @@ def import_submodules(root_module_name: str):
         )
 
     for loader, module_name, is_pkg in pkgutil.walk_packages(
-        root_module.__path__, root_module.__name__ + "."  # type: ignore
+        root_module.__path__,
+        root_module.__name__ + ".",  # type: ignore
     ):
         importlib.import_module(module_name)
 

aredis_om/model/model.py

@@ -22,15 +22,14 @@
     Type,
     TypeVar,
     Union,
-)
-from typing import get_args as typing_get_args
-from typing import (
     no_type_check,
 )
+from typing import get_args as typing_get_args
 
 from more_itertools import ichunked
 from pydantic import BaseModel
 
+
 try:
     from pydantic import ConfigDict, TypeAdapter, field_validator
 
@@ -73,6 +72,7 @@
 from .token_escaper import TokenEscaper
 from .types import Coordinates, CoordinateType, GeoFilter
 
+
 model_registry = {}
 _T = TypeVar("_T")
 Model = TypeVar("Model", bound="RedisModel")
@@ -115,8 +115,11 @@ def convert_datetime_to_timestamp(obj):
     elif isinstance(obj, datetime.datetime):
         return obj.timestamp()
     elif isinstance(obj, datetime.date):
-        # Convert date to datetime at midnight and get timestamp
-        dt = datetime.datetime.combine(obj, datetime.time.min)
+        # Date values represent calendar days, so normalize to UTC midnight
+        # to avoid timezone-dependent day shifts on round-trip conversion.
+        dt = datetime.datetime.combine(
+            obj, datetime.time.min, tzinfo=datetime.timezone.utc
+        )
         return dt.timestamp()
     else:
         return obj
@@ -138,7 +141,9 @@ def convert_timestamp_to_datetime(obj, model_fields):
                     # For Optional[T] which is Union[T, None], get the non-None type
                     args = getattr(field_type, "__args__", ())
                     non_none_types = [
-                        arg for arg in args if arg is not type(None)  # noqa: E721
+                        arg
+                        for arg in args
+                        if arg is not type(None)  # noqa: E721
                     ]
                     if len(non_none_types) == 1:
                         field_type = non_none_types[0]
@@ -150,8 +155,13 @@ def convert_timestamp_to_datetime(obj, model_fields):
                     try:
                         if isinstance(value, str):
                             value = float(value)
-                        # Use fromtimestamp to preserve local timezone behavior
-                        dt = datetime.datetime.fromtimestamp(value)
+                        # Return UTC-aware datetime for consistency.
+                        # Timestamps are always UTC-referenced, so we return
+                        # UTC-aware datetimes. Users can convert to their
+                        # preferred timezone with dt.astimezone(tz).
+                        dt = datetime.datetime.fromtimestamp(
+                            value, datetime.timezone.utc
+                        )
                         # If the field is specifically a date, convert to date
                         if field_type is datetime.date:
                             result[key] = dt.date()
@@ -255,7 +265,9 @@ def convert_base64_to_bytes(obj, model_fields):
                     # For Optional[T] which is Union[T, None], get the non-None type
                     args = getattr(field_type, "__args__", ())
                     non_none_types = [
-                        arg for arg in args if arg is not type(None)  # noqa: E721
+                        arg
+                        for arg in args
+                        if arg is not type(None)  # noqa: E721
                     ]
                     if len(non_none_types) == 1:
                         field_type = non_none_types[0]
@@ -636,10 +648,10 @@ def embedded(cls):
 
 def is_supported_container_type(typ: Optional[type]) -> bool:
     # TODO: Wait, why don't we support indexing sets?
-    if typ == list or typ == tuple or typ == Literal:
+    if typ is list or typ is tuple or typ is Literal:
         return True
     unwrapped = get_origin(typ)
-    return unwrapped == list or unwrapped == tuple or unwrapped == Literal
+    return unwrapped is list or unwrapped is tuple or unwrapped is Literal
 
 
 def validate_model_fields(model: Type["RedisModel"], field_values: Dict[str, Any]):
@@ -1056,7 +1068,7 @@ def _validate_deep_field_path(self, field_path: str):
                         field_type, RedisModel
                     ):
                         current_model = field_type
-                    elif field_type == dict:
+                    elif field_type is dict:
                         # Dict fields - we can't validate nested paths, just accept them
                         return
                     else:
@@ -1089,7 +1101,7 @@ def _validate_deep_field_path(self, field_path: str):
                             field_type, RedisModel
                         ):
                             current_model = field_type
-                        elif field_type == dict:
+                        elif field_type is dict:
                             return  # Can't validate further into dict
                         else:
                             raise QueryNotSupportedError(
@@ -1174,18 +1186,18 @@ def _convert_projected_fields(self, raw_data: Dict[str, str]) -> Dict[str, Any]:
                     field_type = getattr(field_info, "type_", str)
 
                 # Handle common type conversions directly for efficiency
-                if field_type == int:
+                if field_type is int:
                     converted_data[field_name] = int(raw_value)
-                elif field_type == float:
+                elif field_type is float:
                     converted_data[field_name] = float(raw_value)
-                elif field_type == bool:
+                elif field_type is bool:
                     # Redis may store bool as "True"/"False" or "1"/"0"
                     converted_data[field_name] = raw_value.lower() in (
                         "true",
                         "1",
                         "yes",
                     )
-                elif field_type == str:
+                elif field_type is str:
                     converted_data[field_name] = raw_value
                 else:
                     # For complex types, keep as string (could be enhanced later)
@@ -1231,7 +1243,7 @@ def _has_complex_projected_fields(self) -> bool:
             field_type = getattr(field_info, "annotation", None)
 
             # Check for dict fields
-            if field_type == dict:
+            if field_type is dict:
                 return True
 
             # Check for embedded models (subclasses of RedisModel)
@@ -1524,8 +1536,7 @@ def expand_tag_value(value):
             return "|".join([escaper.escape(str(v)) for v in value])
         except TypeError:
             log.debug(
-                "Escaping single non-iterable value used for an IN or "
-                "NOT_IN query: %s",
+                "Escaping single non-iterable value used for an IN or NOT_IN query: %s",
                 value,
             )
         return escaper.escape(str(value))
@@ -1571,8 +1582,10 @@ def convert_numeric_value(v):
                     if isinstance(v, datetime.date) and not isinstance(
                         v, datetime.datetime
                     ):
-                        # Convert date to datetime at midnight
-                        v = datetime.datetime.combine(v, datetime.time.min)
+                        # Use UTC midnight so query conversion matches storage conversion.
+                        v = datetime.datetime.combine(
+                            v, datetime.time.min, tzinfo=datetime.timezone.utc
+                        )
                     v = v.timestamp()
                 return v
 
@@ -3352,9 +3365,7 @@ def schema_for_type(cls, name, typ: Any, field_info: PydanticFieldInfo):
                 field_info, "separator", SINGLE_VALUE_TAG_FIELD_SEPARATOR
             )
             if getattr(field_info, "full_text_search", False) is True:
-                schema = (
-                    f"{name} TAG SEPARATOR {separator} " f"{name} AS {name}_fts TEXT"
-                )
+                schema = f"{name} TAG SEPARATOR {separator} {name} AS {name}_fts TEXT"
             else:
                 schema = f"{name} TAG SEPARATOR {separator}"
         elif issubclass(typ, RedisModel):