Rename datetime to timestamp variables (#742)

.There were internal variables in OrderedRingBuffer and MovingWindow
that were named with the prefix `datetime` as a way to refer to the
timestamps that are stored, which happened to be represented using a
datetime object, but timestamps are actually what it is stored. To avoid
confusion when reading the code, these variables were renamed from
`_datetime` to `_timestamp`.

Fixes #691

Author: daniel-zullo-frequenz

src/frequenz/sdk/timeseries/_moving_window.py

@@ -150,7 +150,7 @@ def __init__(  # pylint: disable=too-many-arguments
                 given sampling period.
             input_sampling_period: The time interval between consecutive input samples.
             resampler_config: The resampler configuration in case resampling is required.
-            align_to: A datetime object that defines a point in time to which
+            align_to: A timestamp that defines a point in time to which
                 the window is aligned to modulo window size. For further
                 information, consult the class level documentation.
             name: The name of this moving window. If `None`, `str(id(self))` will be
@@ -299,10 +299,10 @@ def window(
         and returns an array.
 
         Args:
-            start: The start of the time interval. If `None`, the start of the
-                window is used.
-            end: The end of the time interval. If `None`, the end of the window
-                is used.
+            start: The start timestamp of the time interval. If `None`, the
+                start of the window is used.
+            end: The end timestamp of the time interval. If `None`, the end of
+                the window is used.
             force_copy: If `True`, the returned array is a copy of the underlying
                 data. Otherwise, if possible, a view of the underlying data is
                 returned.
@@ -402,7 +402,7 @@ def __getitem__(self, key: SupportsIndex | datetime | slice) -> float | ArrayLik
 
         * If the key is an integer, the float value of that key
           at the given position is returned.
-        * If the key is a datetime object, the float value of that key
+        * If the key is a timestamp, the float value of that key
           that corresponds to the timestamp is returned.
         * If the key is a slice of timestamps or integers, an ndarray is returned,
           where the bounds correspond to the slice bounds.

src/frequenz/sdk/timeseries/_ringbuffer/buffer.py

@@ -24,9 +24,9 @@ class Gap:
     """A gap defines the range for which we haven't received values yet."""
 
     start: datetime
-    """Start of the range, inclusive."""
+    """Start timestamp of the range, inclusive."""
     end: datetime
-    """End of the range, exclusive."""
+    """End timestamp of the range, exclusive."""
 
     def contains(self, timestamp: datetime) -> bool:
         """Check if a given timestamp is inside this gap.
@@ -46,11 +46,11 @@ def contains(self, timestamp: datetime) -> bool:
 class OrderedRingBuffer(Generic[FloatArray]):
     """Time aware ringbuffer that keeps its entries sorted by time."""
 
-    _DATETIME_MIN = datetime.min.replace(tzinfo=timezone.utc)
-    """The minimum representable datetime value."""
+    _TIMESTAMP_MIN = datetime.min.replace(tzinfo=timezone.utc)
+    """The minimum representable timestamp."""
 
-    _DATETIME_MAX = datetime.max.replace(tzinfo=timezone.utc)
-    """The maximum representable datetime value."""
+    _TIMESTAMP_MAX = datetime.max.replace(tzinfo=timezone.utc)
+    """The maximum representable timestamp."""
 
     def __init__(
         self,
@@ -82,8 +82,8 @@ def __init__(
         self._time_index_alignment: datetime = align_to
 
         self._gaps: list[Gap] = []
-        self._datetime_newest: datetime = self._DATETIME_MIN
-        self._datetime_oldest: datetime = self._DATETIME_MAX
+        self._timestamp_newest: datetime = self._TIMESTAMP_MIN
+        self._timestamp_oldest: datetime = self._TIMESTAMP_MAX
         self._full_time_range: timedelta = len(self._buffer) * self._sampling_period
 
     @property
@@ -148,17 +148,17 @@ def update(self, sample: Sample[QuantityT]) -> None:
 
         # Don't add outdated entries
         if (
-            timestamp < self._datetime_oldest
-            and self._datetime_oldest != self._DATETIME_MAX
+            timestamp < self._timestamp_oldest
+            and self._timestamp_oldest != self._TIMESTAMP_MAX
         ):
             raise IndexError(
-                f"Timestamp {timestamp} too old (cut-off is at {self._datetime_oldest})."
+                f"Timestamp {timestamp} too old (cut-off is at {self._timestamp_oldest})."
             )
 
         # Update timestamps
-        prev_newest = self._datetime_newest
-        self._datetime_newest = max(self._datetime_newest, timestamp)
-        self._datetime_oldest = self._datetime_newest - (
+        prev_newest = self._timestamp_newest
+        self._timestamp_newest = max(self._timestamp_newest, timestamp)
+        self._timestamp_oldest = self._timestamp_newest - (
             self._full_time_range - self._sampling_period
         )
 
@@ -180,7 +180,7 @@ def time_bound_oldest(self) -> datetime:
         Returns:
             The timestamp of the oldest sample of the ring buffer.
         """
-        return self._datetime_oldest
+        return self._timestamp_oldest
 
     @property
     def time_bound_newest(self) -> datetime:
@@ -191,7 +191,7 @@ def time_bound_newest(self) -> datetime:
             The timestamp of the newest sample of the ring buffer
             or None if the buffer is empty.
         """
-        return self._datetime_newest
+        return self._timestamp_newest
 
     @property
     def oldest_timestamp(self) -> datetime | None:
@@ -242,12 +242,12 @@ def to_internal_index(
         timestamp = self.normalize_timestamp(timestamp)
 
         if not allow_outside_range and (
-            self._datetime_newest + self._sampling_period < timestamp
-            or timestamp < self._datetime_oldest
+            self._timestamp_newest + self._sampling_period < timestamp
+            or timestamp < self._timestamp_oldest
         ):
             raise IndexError(
                 f"Requested timestamp {timestamp} is "
-                f"outside the range [{self._datetime_oldest} - {self._datetime_newest}]"
+                f"outside the range [{self._timestamp_oldest} - {self._timestamp_newest}]"
             )
 
         return self.wrap(
@@ -271,7 +271,7 @@ def get_timestamp(self, index: int) -> datetime | None:
             index: Index to convert.
 
         Returns:
-            Datetime index where the value for the given index can be found.
+            Timestamp where the value for the given index can be found.
                 Or None if the buffer is empty.
         """
         if self.oldest_timestamp is None:
@@ -323,8 +323,8 @@ def window(
         missing entries, they can safely do so.
 
         Args:
-            start: start time of the window.
-            end: end time of the window.
+            start: start timestamp of the window.
+            end: end timestamp of the window.
             force_copy: optional, default True. If True, will always create a
                 copy of the data.
             fill_value: If not None, will use this value to fill missing values.
@@ -476,9 +476,9 @@ def _update_gaps(
 
         if not record_as_missing:
             # Replace all gaps with one if we went far into then future
-            if self._datetime_newest - newest >= self._full_time_range:
+            if self._timestamp_newest - newest >= self._full_time_range:
                 self._gaps = [
-                    Gap(start=self._datetime_oldest, end=self._datetime_newest)
+                    Gap(start=self._timestamp_oldest, end=self._timestamp_newest)
                 ]
                 return
 
@@ -518,11 +518,11 @@ def _cleanup_gaps(self) -> None:
                 w_2 = None
 
             # Delete out-of-date gaps
-            if w_1.end <= self._datetime_oldest:
+            if w_1.end <= self._timestamp_oldest:
                 del self._gaps[i]
             # Update start of gap if it's rolled out of the buffer
-            elif w_1.start < self._datetime_oldest:
-                self._gaps[i].start = self._datetime_oldest
+            elif w_1.start < self._timestamp_oldest:
+                self._gaps[i].start = self._timestamp_oldest
             # If w2 is a subset of w1 we can delete it
             elif w_2 and w_1.start <= w_2.start and w_1.end >= w_2.end:
                 del self._gaps[i + 1]
@@ -682,7 +682,7 @@ def count_valid(self) -> int:
         Returns:
             The number of valid items in this buffer.
         """
-        if self._datetime_newest == self._DATETIME_MIN:
+        if self._timestamp_newest == self._TIMESTAMP_MIN:
             return 0
 
         # Sum of all elements in the gap ranges
@@ -692,15 +692,15 @@ def count_valid(self) -> int:
                 (
                     gap.end
                     # Don't look further back than oldest timestamp
-                    - max(gap.start, self._datetime_oldest)
+                    - max(gap.start, self._timestamp_oldest)
                 )
                 // self._sampling_period
                 for gap in self._gaps
             ),
         )
 
-        start_pos = self.to_internal_index(self._datetime_oldest)
-        end_pos = self.to_internal_index(self._datetime_newest)
+        start_pos = self.to_internal_index(self._timestamp_oldest)
+        end_pos = self.to_internal_index(self._timestamp_newest)
 
         if end_pos < start_pos:
             return len(self._buffer) - start_pos + end_pos + 1 - sum_missing_entries

tests/timeseries/test_moving_window.py

@@ -67,13 +67,13 @@ def init_moving_window(
 
 
 def dt(i: int) -> datetime:  # pylint: disable=invalid-name
-    """Create datetime objects from indices.
+    """Create a timestamp from the given index.
 
     Args:
-        i: Index to create datetime from.
+        i: The index to create a timestamp from.
 
     Returns:
-        Datetime object.
+        The timestamp created from the index.
     """
     return datetime.fromtimestamp(i, tz=timezone.utc)
 

tests/timeseries/test_ringbuffer.py

@@ -192,13 +192,13 @@ def test_timestamp_ringbuffer_missing_parameter(
 
 
 def dt(i: int) -> datetime:  # pylint: disable=invalid-name
-    """Create datetime objects from indices.
+    """Create a timestamp from the given index.
 
     Args:
-        i: Index to create datetime from.
+        i: The index to create a timestamp from.
 
     Returns:
-        Datetime object.
+        The timestamp created from the index.
     """
     return datetime.fromtimestamp(i, tz=timezone.utc)
 

tests/timeseries/test_ringbuffer_serialization.py

@@ -52,9 +52,9 @@ def load_dump_test(dumped: rb.OrderedRingBuffer[Any], path: str) -> None:
     np.testing.assert_equal(dumped[:], loaded[:])
 
     # pylint: disable=protected-access
-    assert dumped._datetime_oldest == loaded._datetime_oldest
+    assert dumped._timestamp_oldest == loaded._timestamp_oldest
     # pylint: disable=protected-access
-    assert dumped._datetime_newest == loaded._datetime_newest
+    assert dumped._timestamp_newest == loaded._timestamp_newest
     # pylint: disable=protected-access
     assert len(dumped._gaps) == len(loaded._gaps)
     # pylint: disable=protected-access