Add a pytest tool to compare time approximately

This tool can compare datetime or timedelta objects approximately, like
pytest.approx(). It uses an absolute 1ms tolerance by default.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

tests/timeseries/_resampling/wall_clock_timer/util.py

@@ -6,6 +6,14 @@
 from datetime import datetime, timedelta, timezone
 from typing import assert_never
 
+# This is not great, we are depending on an internal pytest API, but it is
+# the most convenient way to provide a custom approx() comparison for datetime
+# and timedelta.
+# Other alternatives proven to be even more complex and hacky.
+# It also looks like we are not the only ones doing this, see:
+# https://github.com/pytest-dev/pytest/issues/8395
+from _pytest.python_api import ApproxBase
+
 
 def to_seconds(value: datetime | timedelta | float) -> float:
     """Convert a datetime, timedelta, or float to seconds."""
@@ -34,3 +42,48 @@ def wall_now() -> datetime:
     # isort: on
 
     return mock_datetime.now(timezone.utc)
+
+
+# Pylint complains about abstract-method because _yield_comparisons is not implemented
+# but it is used only in the default __eq__ method, which we are re-defining, so we can
+# ignore it.
+class approx_time(ApproxBase):  # pylint: disable=invalid-name, abstract-method
+    """Perform approximate comparisons for datetime or timedelta objects.
+
+    Inherits from `ApproxBase` to provide a rich comparison output in pytest.
+    """
+
+    expected: datetime | timedelta
+    abs: timedelta
+
+    def __init__(
+        self,
+        expected: datetime | timedelta,
+        *,
+        abs: timedelta = timedelta(milliseconds=1),  # pylint: disable=redefined-builtin
+    ) -> None:
+        """Initialize this instance."""
+        if abs < timedelta():
+            raise ValueError(
+                f"absolute tolerance must be a non-negative timedelta, not {abs}"
+            )
+        super().__init__(expected, abs=abs)
+
+    def __repr__(self) -> str:
+        """Return a string representation of this instance."""
+        return f"{self.expected} ± {self.abs}"
+
+    def __eq__(self, actual: object) -> bool:
+        """Compare this instance with another object."""
+        # We need to split the cases for datetime and timedelta for type checking
+        # reasons.
+        diff: timedelta
+        match (self.expected, actual):
+            case (datetime(), datetime()):
+                diff = self.expected - actual
+            case (timedelta(), timedelta()):
+                diff = self.expected - actual
+            case _:
+                return NotImplemented
+
+        return abs(diff) <= self.abs