Add outside_input_range options to get_nearest_date_idx

src/dolphin/utils.py

@@ -11,7 +11,7 @@
 from itertools import chain
 from multiprocessing import cpu_count
 from pathlib import Path
-from typing import Any, Iterable, Optional, Sequence, Union
+from typing import Any, Iterable, Literal, Optional, Sequence, Union
 
 import numpy as np
 from numpy.typing import ArrayLike, DTypeLike
@@ -695,13 +695,19 @@ def map(self, fn: Callable[P, T], *iterables, **kwargs):  # noqa: D102
 def get_nearest_date_idx(
     input_items: Sequence[datetime.datetime],
     requested: datetime.datetime,
+    outside_input_range: Literal["allow", "warn", "raise"] = "warn",
 ) -> int:
     """Find the index nearest to `requested` within `input_items`."""
     sorted_inputs = sorted(input_items)
     if not sorted_inputs[0] <= requested <= sorted_inputs[-1]:
         msg = f"Requested {requested} falls outside of input range: "
         msg += f"{sorted_inputs[0]}, {sorted_inputs[-1]}"
-        raise ValueError(msg)
+        if outside_input_range == "raise":
+            raise ValueError(msg)
+        elif outside_input_range == "warn":
+            warnings.warn(msg, stacklevel=2)
+        else:
+            pass
 
     nearest_idx = min(
         range(len(input_items)),