hard to say

Author: BriannaLind

src/planet_overlap/pagination.py

@@ -3,10 +3,10 @@
 from typing import List, Tuple, Union
 
 # Thresholds
-POLYGON_AREA_THRESHOLD_KM2 = 2500
-DATE_RANGE_THRESHOLD_DAYS = 30
-POINT_DATE_THRESHOLD_DAYS = 3 * 365
-MAX_SCENES_PER_REQUEST = 500
+POLYGON_AREA_THRESHOLD_KM2 = 2500  # AOI > 2500 km² triggers spatial tiling
+DATE_RANGE_THRESHOLD_DAYS = 30  # Polygons: split if range >30 days
+POINT_DATE_THRESHOLD_DAYS = 3 * 365  # Points: split if range >3 years (~1095 days)
+MAX_SCENES_PER_REQUEST = 500  # Max scenes per slice
 
 
 def estimate_scene_count(days: int, avg_scenes_per_day: float = 1.0) -> int:
@@ -17,25 +17,27 @@ def estimate_scene_count(days: int, avg_scenes_per_day: float = 1.0) -> int:
 def tile_dates(
     start: datetime, end: datetime, is_point: bool = False
 ) -> List[Tuple[datetime, datetime]]:
-    """Break a date range into smaller slices if it exceeds thresholds.
+    """
+    Break a date range into smaller slices if it exceeds thresholds.
 
     Args:
-        start: Start datetime
-        end: End datetime
-        is_point: True if input is a point, False for polygons/AOIs
+        start: start datetime
+        end: end datetime
+        is_point: True if the input is a point, False for polygons/AOIs
 
     Returns:
         List of (start, end) tuples
     """
     total_days = (end - start).days + 1
-    slices = []
+    slices: List[Tuple[datetime, datetime]] = []
 
     threshold_days = (
         POINT_DATE_THRESHOLD_DAYS if is_point else DATE_RANGE_THRESHOLD_DAYS
     )
     if total_days <= threshold_days:
         return [(start, end)]
 
+    # Split into slices
     slice_length = min(threshold_days, total_days)
     current_start = start
     while current_start <= end:
@@ -47,17 +49,28 @@ def tile_dates(
 
 
 def tile_aoi(geom: Union[Polygon, Point]) -> List[Polygon]:
-    """Split a polygon into ~1°x1° tiles if AOI is large.
-    Points are returned as buffered polygons."""
+    """
+    Split a polygon into ~1°x1° tiles if AOI is large.
+    Points are returned as buffered polygons automatically.
+
+    Args:
+        geom: AOI polygon or point
+
+    Returns:
+        List of Polygons for API requests
+    """
     if isinstance(geom, Point):
+        # buffer a small area around the point (~0.01 degrees)
         return [geom.buffer(0.01)]
 
+    # Check area (approximation using degrees -> km²)
     lon_min, lat_min, lon_max, lat_max = geom.bounds
     area_km2 = (lon_max - lon_min) * (lat_max - lat_min) * 111**2
     if area_km2 <= POLYGON_AREA_THRESHOLD_KM2:
         return [geom]
 
-    tiles = []
+    # Split polygon into 1°x1° tiles
+    tiles: List[Polygon] = []
     lat = lat_min
     while lat < lat_max:
         lon = lon_min
@@ -84,9 +97,16 @@ def fetch_planet_data(
     max_cloud: float = 0.5,
     min_sun_angle: float = 0.0,
 ):
-    """Main entry point to fetch Planet data,
-    automatically tiling AOIs or temporal ranges."""
-    ids, geometries, properties = [], [], []
+    """
+    Main entry point to fetch Planet data, automatically tiling AOIs or
+    temporal ranges when thresholds are exceeded.
+
+    Returns:
+        ids, geometries, properties
+    """
+    ids: List[str] = []
+    geometries: List[dict] = []
+    properties: List[dict] = []
 
     for geom in aois:
         is_point = isinstance(geom, Point)
@@ -97,7 +117,7 @@ def fetch_planet_data(
                 date_slices = tile_dates(start, end, is_point=is_point)
 
                 for s_start, s_end in date_slices:
-                    # Mock data for demonstration
+                    # Example: mock appending data
                     ids.append(f"scene_{s_start.strftime('%Y%m%d')}")
                     geometries.append(tile.__geo_interface__)
                     properties.append(