Handle filter_temporal end-exclusiveness in DateTimeInterval #955

Author: soxofaan

openeo/metadata/__init__.py

@@ -23,6 +23,7 @@
 from openeo.internal.jupyter import render_component
 from openeo.metadata._extents import _EmptyExtent, _NonConcreteExtent
 from openeo.util import Rfc3339, deep_get
+from openeo.utils.datastructure import is_2_tuple_like
 from openeo.utils.datetime import DateTimeInterval
 from openeo.utils.normalize import normalize_resample_resolution, unique
 
@@ -121,7 +122,9 @@ def filter_temporal(self, extent: Tuple[str | None, str | None] | List[str | Non
         """
         Create new TemporalDimension with intersection current and given temporal extents.
         """
-        if (interval1 := DateTimeInterval.try_from(self.extent)) and (interval2 := DateTimeInterval.try_from(extent)):
+        if is_2_tuple_like(self.extent) and is_2_tuple_like(extent):
+            interval1 = DateTimeInterval(*self.extent)
+            interval2 = DateTimeInterval(*extent, end_inclusive=False)
             if intersection := interval1.intersection(interval2):
                 new_extent = intersection.as_rfc3339()
             else:

openeo/utils/datastructure.py

@@ -6,6 +6,14 @@
 from typing import Container
 
 
+def is_2_tuple_like(x) -> bool:
+    """
+    Is given value like a 2-tuple: a sequence of length 2,
+    e.g. usable as `*args` in a function call?
+    """
+    return isinstance(x, (list, tuple)) and len(x) == 2
+
+
 def make_new_key(container: Container[str], key: str, *, start: int = 1):
     """
     Construct a new key that doesn't exist yet in the given container (dict, set, ...),

openeo/utils/datetime.py

@@ -46,35 +46,29 @@ class DateTimeInterval:
     Datetime interval, defined by a start and end datetime instant (UTC)
     each of which can be ``None`` to indicate being open-ended in that direction (no limit).
 
-    Note on including or excluding the end instant:
-    this is not a property of the extent itself, but is an aspect of what the extent describes or how it is used:
-    - when the extent describes the range of a certain data set, the end instant is inclusive
-    - when the extent is used as search window for a query, the end instant is typically handled as exclusive
+    Note on including or excluding the end instant (attribute ``end_inclusive``):
+    this aspect is usually linked to what the extent describes or how it is used:
+      - when the extent describes the known time range of a certain data set (e.g. a STAC collection),
+        the end instant is inclusive
+      - when the extent is used as search window for a query/filter operation,
+        some standards (e.g. openEO ``filter_temporal``) prescribe the end instant as exclusive,
+        as this simplifies some aspects of the query logic and specification.
+    The ``end_inclusive`` attribute can be toggled to indicate the intended semantics where this matters.
     """
 
     start: Union[datetime.datetime, None]
     end: Union[datetime.datetime, None]
+    end_inclusive: bool = dataclasses.field(default=True, kw_only=True)
 
-    def __init__(self, start: DateTimeLike | None, end: DateTimeLike | None):
+    def __init__(self, start: DateTimeLike | None, end: DateTimeLike | None, *, end_inclusive: bool = True):
         start = to_datetime_utc_unless_none(start)
         end = to_datetime_utc_unless_none(end)
         if start and end and end < start:
             raise ValueError(f"End instant {end!r} is before start instant {start!r}")
 
         object.__setattr__(self, "start", start)
         object.__setattr__(self, "end", end)
-
-    @classmethod
-    def try_from(cls, x: Any) -> DateTimeInterval | None:
-        """Try to build a TemporalExtent from the given object, or return None if not possible."""
-        try:
-            if isinstance(x, (list, tuple)) and len(x) == 2:
-                return DateTimeInterval(*x)
-            elif isinstance(x, dict):
-                return DateTimeInterval(**x)
-        except (ValueError, TypeError):
-            pass
-        return None
+        object.__setattr__(self, "end_inclusive", end_inclusive)
 
     def as_tuple(self) -> Tuple[datetime.datetime | None, datetime.datetime | None]:
         return self.start, self.end
@@ -110,14 +104,14 @@ def intersection(self, other: DateTimeInterval) -> DateTimeInterval | None:
             start = max(self.start, other.start)
 
         if self.end is None:
-            end = other.end
+            end, end_inclusive = other.end, other.end_inclusive
         elif other.end is None:
-            end = self.end
+            end, end_inclusive = self.end, self.end_inclusive
         else:
-            end = min(self.end, other.end)
+            end, end_inclusive = min((self.end, self.end_inclusive), (other.end, other.end_inclusive))
 
         # Double check naive calculation on emptiness
-        if start is not None and end is not None and end < start:
+        if start is not None and end is not None and (end < start or (end == start and not end_inclusive)):
             return None
 
-        return DateTimeInterval(start, end)
+        return DateTimeInterval(start, end, end_inclusive=end_inclusive)

tests/metadata/test_metadata.py

@@ -61,6 +61,16 @@ def test_filter_temporal_empty_intersection(self):
         assert tdim1.extent == ("2021-01-01", None)
         assert isinstance(tdim2.extent, _EmptyExtent)
 
+    def test_filter_temporal_end_inclusive(self):
+        """`filter_temporal` is end-exclusive"""
+        tdim1 = TemporalDimension(name="t", extent=("2026-03-01", "2026-04-01"))
+        # `filter_temporal` with extent just before: no match
+        tdim2 = tdim1.filter_temporal(extent=("2026-02-01", "2026-03-01"))
+        assert tdim2.extent == _EmptyExtent()
+        # `filter_temporal` with extent just after: single instant match
+        tdim3 = tdim1.filter_temporal(extent=("2026-04-01", "2026-05-01"))
+        assert tdim3.extent == ("2026-04-01T00:00:00Z", "2026-04-01T00:00:00Z")
+
     def test_filter_temporal_none(self):
         tdim1 = TemporalDimension(name="t", extent=("2021-01-01", None))
         tdim2 = tdim1.filter_temporal(extent=None)

tests/utils/test_datastructure.py

@@ -1,4 +1,16 @@
-from openeo.utils.datastructure import make_new_key
+from openeo.utils.datastructure import is_2_tuple_like, make_new_key
+
+
+def test_is_2_tuple_like():
+    assert is_2_tuple_like((1, 2))
+    assert is_2_tuple_like([1, 2])
+    assert not is_2_tuple_like((1,))
+    assert not is_2_tuple_like([1])
+    assert not is_2_tuple_like((1, 2, 3))
+    assert not is_2_tuple_like([1, 2, 3])
+    assert not is_2_tuple_like("12")
+    assert not is_2_tuple_like(12)
+    assert not is_2_tuple_like(None)
 
 
 def test_make_new_key_on_dict():

tests/utils/test_datetime.py

@@ -113,20 +113,25 @@ def test_init_basic_datetime_timezone(self):
         assert interval.end == datetime.datetime(2026, 11, 12, 23, 52, 22, tzinfo=datetime.timezone.utc)
 
     @pytest.mark.parametrize(
-        ["given", "expected"],
+        ["interval", "expected"],
         [
-            (["2026-09-10", "2026-11-12"], DateTimeInterval("2026-09-10", "2026-11-12")),
-            (("2026-09-10", "2026-11-12"), DateTimeInterval("2026-09-10", "2026-11-12")),
-            ({"start": "2026-09-10", "end": "2026-11-12"}, DateTimeInterval("2026-09-10", "2026-11-12")),
-            ("foobar", None),
-            (["2026-09-10"], None),
-            (["2026-09-10", "2026-11-12", "2026-12-01"], None),
-            ({"color": "green"}, None),
-            ({"start": "2026-09-10"}, None),
+            (DateTimeInterval("2026-09-10", "2026-09-20"), True),
+            (DateTimeInterval("2026-09-10T00:00:00", "2026-09-20T00:00:00"), True),
+            (DateTimeInterval("2026-09-10T01:00:00+01:00", "2026-09-20T00:00:00"), True),
+            (DateTimeInterval("2026-09-10T01:00:00", "2026-09-20T00:00:00"), False),
         ],
     )
-    def test_try_from(self, given, expected):
-        assert DateTimeInterval.try_from(given) == expected
+    def test_equality(self, interval, expected):
+        ref = DateTimeInterval("2026-09-10", "2026-09-20")
+        assert (ref == interval) == expected
+        assert (interval == ref) == expected
+
+    def test_equality_end_inclusive(self):
+        d1 = "2026-09-10"
+        d2 = "2026-09-20"
+        assert DateTimeInterval(d1, d2) == DateTimeInterval(d1, d2, end_inclusive=True)
+        assert DateTimeInterval(d1, d2) != DateTimeInterval(d1, d2, end_inclusive=False)
+        assert DateTimeInterval(d1, d2, end_inclusive=False) == DateTimeInterval(d1, d2, end_inclusive=False)
 
     def test_as_tuple(self):
         interval = DateTimeInterval("2026-09-10", "2026-11-12T11:22:33Z")
@@ -174,3 +179,27 @@ def test_intersection(self, interval1, interval2, expected):
         interval2 = DateTimeInterval(*interval2)
         assert interval1.intersection(interval2) == expected
         assert interval2.intersection(interval1) == expected
+
+    @pytest.mark.parametrize(
+        ["interval1", "interval2", "expected"],
+        [
+            (
+                DateTimeInterval("2026-08-20", "2026-09-01"),
+                DateTimeInterval("2026-09-01", "2026-09-30"),
+                DateTimeInterval("2026-09-01", "2026-09-01"),
+            ),
+            (
+                DateTimeInterval("2026-08-20", "2026-09-01", end_inclusive=False),
+                DateTimeInterval("2026-09-01", "2026-09-30"),
+                None,
+            ),
+            (
+                DateTimeInterval("2026-08-20", "2026-09-01", end_inclusive=False),
+                DateTimeInterval("2026-08-25", "2026-09-30"),
+                DateTimeInterval("2026-08-25", "2026-09-01", end_inclusive=False),
+            ),
+        ],
+    )
+    def test_intersection_end_inclusive(self, interval1, interval2, expected):
+        assert interval1.intersection(interval2) == expected
+        assert interval2.intersection(interval1) == expected