Handle filter_temporal end-exclusiveness in DateTimeInterval #955

Author: soxofaan

openeo/metadata/__init__.py

@@ -121,7 +121,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 (interval1 := DateTimeInterval.try_from_tuple(self.extent)) and (
+            interval2 := DateTimeInterval.try_from_tuple(extent, end_inclusive=False)
+        ):
             if intersection := interval1.intersection(interval2):
                 new_extent = intersection.as_rfc3339()
             else:

openeo/utils/datetime.py

@@ -2,6 +2,7 @@
 
 import dataclasses
 import datetime
+import sys
 from typing import Any, Tuple, Union
 
 import dateutil.parser
@@ -46,34 +47,38 @@ 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} if sys.version_info >= (3, 10) else {}))
 
-    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)
+        object.__setattr__(self, "end_inclusive", end_inclusive)
 
     @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
+    def try_from_tuple(cls, x: Any, **kwargs: Any) -> DateTimeInterval | None:
+        """Try to build a TemporalExtent from the given tuple/list, or return None if not possible."""
+        if isinstance(x, (list, tuple)) and len(x) == 2:
+            try:
+                return DateTimeInterval(*x, **kwargs)
+            except (ValueError, TypeError):
+                pass
         return None
 
     def as_tuple(self) -> Tuple[datetime.datetime | None, datetime.datetime | None]:
@@ -110,14 +115,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/rest/datacube/test_datacube.py

@@ -473,7 +473,6 @@ def test_filter_temporal_generic(self, s2cube, args, kwargs, extent):
             (["2016", "2017"], ["2016-01-01", "2017-01-01"]),
             (["2016-03", "2016-04"], ["2016-03-01", "2016-04-01"]),
             (["2016-03", "2018-12"], ["2016-03-01", "2018-12-01"]),
-            (["2016", "2016-01"], ["2016-01-01", "2016-01-01"]),
             (["2016", "2016-04"], ["2016-01-01", "2016-04-01"]),
             ([None, "2016-04"], [None, "2016-04-01"]),
         ],

tests/utils/test_datetime.py

@@ -112,22 +112,43 @@ def test_init_basic_datetime_timezone(self):
         assert interval.start == datetime.datetime(2026, 9, 10, 9, 11, 11, tzinfo=datetime.timezone.utc)
         assert interval.end == datetime.datetime(2026, 11, 12, 23, 52, 22, tzinfo=datetime.timezone.utc)
 
+    @pytest.mark.parametrize(
+        ["interval", "expected"],
+        [
+            (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_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)
+
     @pytest.mark.parametrize(
         ["given", "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")),
+            (("2026-09-10", None), DateTimeInterval("2026-09-10", None)),
+            (["2026-09-10", "2026-11-12"], DateTimeInterval("2026-09-10", "2026-11-12")),
+            (None, None),
             ("foobar", None),
             (["2026-09-10"], None),
             (["2026-09-10", "2026-11-12", "2026-12-01"], None),
-            ({"color": "green"}, None),
-            ({"start": "2026-09-10"}, None),
+            ([{"2026": "09-10"}, {"2026": "11-12"}], None),
+            ({"2026": "09-10"}, None),
         ],
     )
     def test_try_from(self, given, expected):
-        assert DateTimeInterval.try_from(given) == expected
-
+        assert DateTimeInterval.try_from_tuple(given) == expected
     def test_as_tuple(self):
         interval = DateTimeInterval("2026-09-10", "2026-11-12T11:22:33Z")
         assert interval.as_tuple() == (
@@ -174,3 +195,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