feat: add delta utility properties and constructors

Author: Rodrigo Roldán

src/eones/core/delta.py

@@ -177,6 +177,16 @@ def scale(self, factor: int) -> "Delta":
         """
         return Delta(**{k: v * factor for k, v in self.to_input_dict().items()})
 
+    @property
+    def total_months(self) -> int:
+        """Return the calendar component expressed as total months."""
+        return self._calendar.total_months
+
+    @property
+    def total_seconds(self) -> int:
+        """Return the duration component expressed as total seconds."""
+        return self._duration.total_seconds
+
     def is_zero(self) -> bool:
         """
         Check if the delta has no effect.
@@ -263,3 +273,14 @@ def from_iso(cls, iso: str) -> "Delta":
             raise ValueError(f"Invalid ISO delta: {iso}")
         parts = {k: int(v) for k, v in match.groupdict().items() if v is not None}
         return cls(**parts)
+
+    @classmethod
+    def from_timedelta(cls, td: "timedelta") -> "Delta":
+        """Create a Delta instance from :class:`datetime.timedelta`."""
+        from datetime import timedelta
+
+        if not isinstance(td, timedelta):
+            raise TypeError(f"'td' must be timedelta, got {type(td).__name__}")
+
+        duration = DeltaDuration.from_timedelta(td)
+        return cls(**duration.to_input_dict())

src/eones/core/delta_calendar.py

@@ -90,6 +90,11 @@ def scale(self, factor: int) -> "DeltaCalendar":
         items = self.to_input_dict().items()
         return DeltaCalendar(**{k: v * factor for k, v in items})
 
+    @property
+    def total_months(self) -> int:
+        """Return the delta expressed as total months."""
+        return self.years * 12 + self.months
+
     def to_dict(self) -> Dict[str, int]:
         """
         Return a normalized version of the delta.

src/eones/core/delta_duration.py

@@ -105,6 +105,11 @@ def scale(self, factor: int) -> "DeltaDuration":
             **{key: value * factor for key, value in self._input.items()}
         )
 
+    @property
+    def total_seconds(self) -> int:
+        """Return the duration expressed in total seconds."""
+        return int(self.timedelta.total_seconds())
+
     def is_zero(self) -> bool:
         """
         Check if the duration is equivalent to zero.
@@ -144,6 +149,29 @@ def to_iso(self) -> str:
 
         return result or "P0D"
 
+    @classmethod
+    def from_timedelta(cls, td: timedelta) -> "DeltaDuration":
+        """Create a DeltaDuration from a :class:`datetime.timedelta`."""
+        if not isinstance(td, timedelta):
+            raise TypeError(f"'td' must be timedelta, got {type(td).__name__}")
+
+        total_seconds = int(td.total_seconds())
+        sign = -1 if total_seconds < 0 else 1
+        total_seconds = abs(total_seconds)
+
+        days, rem = divmod(total_seconds, 86400)
+        weeks, days = divmod(days, 7)
+        hours, rem = divmod(rem, 3600)
+        minutes, seconds = divmod(rem, 60)
+
+        return cls(
+            weeks=weeks * sign,
+            days=days * sign,
+            hours=hours * sign,
+            minutes=minutes * sign,
+            seconds=seconds * sign,
+        )
+
     @classmethod
     def from_iso(cls, iso: str) -> "DeltaDuration":
         """

tests/test_delta.py

@@ -1,4 +1,4 @@
-from datetime import datetime
+from datetime import datetime, timedelta
 from zoneinfo import ZoneInfo
 
 import pytest
@@ -245,3 +245,18 @@ def test_from_iso_time_only():
 def test_from_iso_invalid():
     with pytest.raises(ValueError):
         Delta.from_iso("XYZ")
+
+
+def test_total_properties_and_from_timedelta():
+    td = timedelta(days=1, hours=2, minutes=3, seconds=4)
+    delta = Delta.from_timedelta(td)
+    assert delta.to_input_dict() == {
+        "days": 1,
+        "hours": 2,
+        "minutes": 3,
+        "seconds": 4,
+    }
+
+    combined = Delta(years=1, months=2, days=1, hours=1)
+    assert combined.total_months == 14
+    assert combined.total_seconds == timedelta(days=1, hours=1).total_seconds()