feature: add support for delta in __add__ & __sub__

Author: Rodrigo Roldán

src/eones/core/date.py

@@ -4,12 +4,15 @@
 
 from calendar import monthrange
 from datetime import datetime, timedelta, timezone
-from typing import Any, Literal, Optional, Union
+from typing import TYPE_CHECKING, Any, Literal, Optional, Union
 from zoneinfo import ZoneInfo
 
 from eones.constants import VALID_KEYS
 from eones.humanize import diff_for_humans as _diff_for_humans
 
+if TYPE_CHECKING:  # pragma: no cover - import for type checking only
+    from eones.core.delta import Delta
+
 
 class Date:  # pylint: disable=too-many-public-methods
     """
@@ -90,15 +93,49 @@ def shift(self, delta: timedelta) -> Date:
         """Return a new Date shifted by the given timedelta."""
         return self._with(self._dt + delta)
 
-    def __add__(self, delta: timedelta) -> Date:
-        return self.shift(delta)
+    def __add__(self, delta: Union[timedelta, "Delta"]) -> Date:
+        """Return a new :class:`Date` offset by ``delta``.
+
+        Both :class:`datetime.timedelta` and :class:`eones.core.delta.Delta`
+        instances are accepted. The operation returns a new ``Date`` shifted
+        forward by the provided amount.
+
+        Returns:
+            Date: The resulting shifted date.
+        """
+        from eones.core.delta import Delta
+
+        if isinstance(delta, Delta):
+            return delta.apply(self)
+
+        if isinstance(delta, timedelta):
+            return self.shift(delta)
+
+        return NotImplemented
+
+    def __sub__(self, other: Union[Date, timedelta, "Delta"]) -> Union[Date, timedelta]:
+        """Subtract ``other`` from this date.
+
+        ``other`` may be a :class:`datetime.timedelta` or a
+        :class:`eones.core.delta.Delta`. Timedelta or Delta instances yield a new
+        ``Date`` shifted backward. When another ``Date`` is provided, the result
+        is the difference as a ``timedelta``.
+
+        Returns:
+            Union[Date, timedelta]: ``Date`` or time difference depending on the
+            operand type.
+        """
+        from eones.core.delta import Delta
+
+        if isinstance(other, Delta):
+            return other.invert().apply(self)
 
-    def __sub__(self, other: Union[Date, timedelta]) -> Union[Date, timedelta]:
         if isinstance(other, timedelta):
             return self.shift(-other)
 
         if isinstance(other, Date):
             return self._dt - other.to_datetime()
+
         return NotImplemented
 
     @classmethod

tests/test_date.py

@@ -5,6 +5,7 @@
 import pytest
 
 from eones.core.date import Date
+from eones.core.delta import Delta
 
 # ==== Fixtures ====
 
@@ -37,9 +38,6 @@ def test_previous_weekday_variants(start, target, expected_day):
     assert prev.to_datetime().day == expected_day
 
 
-# (todo el resto del archivo como ya está, pero sin repeticiones)
-
-
 # ==== truncate / round ====
 
 
@@ -156,6 +154,14 @@ def test_date_shift_and_add_operator():
     assert added.to_datetime().day == 6
 
 
+def test_date_add_delta():
+    d = Date(datetime(2024, 1, 31, tzinfo=ZoneInfo("UTC")))
+    result = d + Delta(months=1)
+    dt = result.to_datetime()
+    assert dt.month == 2
+    assert dt.day == 29
+
+
 def test_date_subtract_timedelta():
     d = Date(datetime(2024, 1, 10, tzinfo=ZoneInfo("UTC")))
     result = d - timedelta(days=3)
@@ -169,6 +175,14 @@ def test_date_subtract_another_date():
     assert delta.days == 5
 
 
+def test_date_subtract_delta():
+    d = Date(datetime(2024, 3, 31, tzinfo=ZoneInfo("UTC")))
+    result = d - Delta(months=1)
+    dt = result.to_datetime()
+    assert dt.month == 2
+    assert dt.day == 29
+
+
 def test_date_sub_invalid_type_triggers_not_implemented():
     d = Date(datetime(2024, 1, 1, tzinfo=ZoneInfo("UTC")))
     with pytest.raises(TypeError):
@@ -264,7 +278,7 @@ def test_date_less_than_another():
 def test_date_less_than_invalid_type():
     dt = Date(datetime(2024, 1, 1, tzinfo=ZoneInfo("UTC")))
     with pytest.raises(TypeError):
-        _ = dt < "2024-01-02"  # activa NotImplemented
+        _ = dt < "2024-01-02"
 
 
 def test_date_equality_with_another_date():
@@ -275,7 +289,7 @@ def test_date_equality_with_another_date():
 
 def test_date_equality_with_other_type():
     dt = Date(datetime(2024, 1, 1, tzinfo=ZoneInfo("UTC")))
-    assert (dt == "2024-01-01") is False  # activa return NotImplemented
+    assert (dt == "2024-01-01") is False
 
 
 def test_date_hash():
@@ -286,49 +300,41 @@ def test_date_hash():
 @pytest.mark.parametrize(
     "unit, dt_kwargs, expected",
     [
-        # Año
         (
             "year",
             {"year": 2024, "month": 1, "day": 1},
             {"month": 12, "day": 31, "hour": 23, "minute": 59},
         ),
-        # Mes normal
         (
             "month",
             {"year": 2024, "month": 4, "day": 1},
             {"day": 30, "hour": 23, "minute": 59},
         ),
-        # Mes bisiesto febrero
         (
             "month",
             {"year": 2024, "month": 2, "day": 1},
             {"day": 29, "hour": 23, "minute": 59},
         ),
-        # Semana que arranca lunes y debe terminar domingo
         (
             "week",
             {"year": 2024, "month": 4, "day": 1},
             {"weekday": 6, "hour": 23, "minute": 59},
         ),
-        # Día
         (
             "day",
             {"year": 2024, "month": 4, "day": 1, "hour": 10},
             {"hour": 23, "minute": 59, "second": 59},
         ),
-        # Hora
         (
             "hour",
             {"year": 2024, "month": 4, "day": 1, "hour": 10},
             {"minute": 59, "second": 59},
         ),
-        # Minuto
         (
             "minute",
             {"year": 2024, "month": 4, "day": 1, "hour": 10, "minute": 25},
             {"second": 59},
         ),
-        # Segundo
         (
             "second",
             {
@@ -346,18 +352,13 @@ def test_date_hash():
 def test_ceil_units(unit, dt_kwargs, expected):
     base = Date(datetime(**dt_kwargs, tzinfo=ZoneInfo("UTC")))
     result = base.ceil(unit).to_datetime()
-
-    # Validación del tipo de retorno
     assert isinstance(result, datetime)
-
-    # Validaciones específicas por atributo
     for attr, value in expected.items():
         if attr == "weekday":
             assert result.weekday() == value
         else:
             assert getattr(result, attr) == value
 
-    # Validación general: el resultado debe ser igual o posterior
     assert result >= base.to_datetime()
 
 
@@ -382,17 +383,15 @@ def test_ceil_second_sets_microsecond():
 
 
 def test_ceil_invalid_unit_only_in_ceil():
-    # "decade" es aceptado por floor() si no lo valida, pero no por ceil()
     d = Date(datetime(2024, 1, 1, tzinfo=ZoneInfo("UTC")))
-    d._dt = d._dt.replace(tzinfo=ZoneInfo("UTC"))  # asegurar zona válida
+    d._dt = d._dt.replace(tzinfo=ZoneInfo("UTC"))
     with pytest.raises(ValueError, match="Unsupported unit: decade"):
         d.ceil("decade")
 
 
 def test_ceil_final_else_branch_direct():
     class Dummy(Date):
         def floor(self, unit):
-            # Simula un floor válido para forzar ejecución del bloque final de ceil
             return self
 
     d = Dummy(datetime(2024, 1, 1, tzinfo=ZoneInfo("UTC")))
@@ -401,7 +400,7 @@ def floor(self, unit):
 
 
 def test_date_naive_unknown_mode_raises():
-    dt = datetime(2024, 1, 1, 12, 0)  # sin tzinfo
+    dt = datetime(2024, 1, 1, 12, 0)
     with pytest.raises(ValueError, match="Invalid 'naive' value"):
         Date(dt, tz="UTC", naive="xyz")