feat(geo): enhance GeoFilter with validation and documentation

- Add comprehensive docstrings to GeoFilter class with usage examples
- Add coordinate validation (longitude: -180 to 180, latitude: -90 to 90)
- Add radius validation (must be positive)
- Add from_coordinates() convenience class method
- Improve error messages with actual invalid values
- Add return type hints for better type safety
- Add clarifying comments in tests about distance calculations

These improvements address GitHub Copilot suggestions and enhance
the robustness and usability of the geographic filtering feature.

Author: bsbodden

aredis_om/model/types.py

@@ -1,4 +1,4 @@
-from typing import Annotated, Any, Literal
+from typing import Annotated, Any, Literal, Tuple, Union
 
 from pydantic import BeforeValidator, PlainSerializer
 from pydantic_extra_types.coordinate import Coordinate
@@ -8,33 +8,99 @@
 
 
 class GeoFilter:
-    def __init__(self, longitude: float, latitude: float, radius: float, unit: RadiusUnit):
+    """
+    A geographic filter for searching within a radius of a coordinate point.
+
+    This filter is used with GEO fields to find models within a specified
+    distance from a given location.
+
+    Args:
+        longitude: The longitude of the center point (-180 to 180)
+        latitude: The latitude of the center point (-90 to 90)
+        radius: The search radius (must be positive)
+        unit: The unit of measurement ('m', 'km', 'mi', or 'ft')
+
+    Example:
+        >>> # Find all locations within 10 miles of Portland, OR
+        >>> filter = GeoFilter(
+        ...     longitude=-122.6765,
+        ...     latitude=45.5231,
+        ...     radius=10,
+        ...     unit="mi"
+        ... )
+        >>> results = await Location.find(
+        ...     Location.coordinates == filter
+        ... ).all()
+    """
+
+    def __init__(
+        self, longitude: float, latitude: float, radius: float, unit: RadiusUnit
+    ):
+        # Validate coordinates
+        if not -180 <= longitude <= 180:
+            raise ValueError(f"Longitude must be between -180 and 180, got {longitude}")
+        if not -90 <= latitude <= 90:
+            raise ValueError(f"Latitude must be between -90 and 90, got {latitude}")
+        if radius <= 0:
+            raise ValueError(f"Radius must be positive, got {radius}")
+
         self.longitude = longitude
         self.latitude = latitude
         self.radius = radius
         self.unit = unit
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"{self.longitude} {self.latitude} {self.radius} {self.unit}"
 
+    @classmethod
+    def from_coordinates(
+        cls, coords: Coordinate, radius: float, unit: RadiusUnit
+    ) -> "GeoFilter":
+        """
+        Create a GeoFilter from a Coordinates object.
+
+        Args:
+            coords: A Coordinate object with latitude and longitude
+            radius: The search radius
+            unit: The unit of measurement
+
+        Returns:
+            A new GeoFilter instance
+        """
+        return cls(coords.longitude, coords.latitude, radius, unit)
+
 
 CoordinateType = Coordinate
 
 
-def parse_redis(v: Any):
+def parse_redis(v: Any) -> Union[Tuple[str, str], Any]:
     """
+    Transform Redis coordinate format to Pydantic coordinate format.
+
     The pydantic coordinate type expects a string in the format 'latitude,longitude'.
-    Redis expects a string in the format 'longitude,latitude'.
+    Redis stores coordinates in the format 'longitude,latitude'.
 
     This validator transforms the input from Redis into the expected format for pydantic.
+
+    Args:
+        v: The value from Redis (typically a string like "longitude,latitude")
+
+    Returns:
+        A tuple of (latitude, longitude) strings if input is a coordinate string,
+        otherwise returns the input unchanged.
+
+    Raises:
+        ValueError: If the coordinate string format is invalid
     """
     if isinstance(v, str):
         parts = v.split(",")
 
         if len(parts) != 2:
-            raise ValueError("Invalid coordinate format")
+            raise ValueError(
+                f"Invalid coordinate format. Expected 'longitude,latitude' but got: {v}"
+            )
 
-        return (parts[1], parts[0])
+        return (parts[1], parts[0])  # Swap to (latitude, longitude)
 
     return v
 

tests/test_hash_model.py

@@ -1149,6 +1149,8 @@ class Meta:
     longitude = -122.6765
 
     loc1 = Location(coordinates=(latitude, longitude), name="Portland")
+    # Offset by 0.01 degrees (~1.1 km at this latitude) to create a nearby location
+    # This ensures "Nearby" is within the 10 mile search radius but not at the exact same location
     loc2 = Location(coordinates=(latitude + 0.01, longitude + 0.01), name="Nearby")
 
     await loc1.save()

tests/test_json_model.py

@@ -1459,6 +1459,8 @@ class Meta:
     longitude = -122.6765
 
     loc1 = Location(coordinates=(latitude, longitude), name="Portland")
+    # Offset by 0.01 degrees (~1.1 km at this latitude) to create a nearby location
+    # This ensures "Nearby" is within the 10 mile search radius but not at the exact same location
     loc2 = Location(coordinates=(latitude + 0.01, longitude + 0.01), name="Nearby")
 
     await loc1.save()