Rename alignment arguments to align_to and make them default to UNIX_EPOCH (#349)

This is to make it consistent with the resampler.

Fixes #343.

Author: llucax

RELEASE_NOTES.md

@@ -52,6 +52,8 @@
 
     Note that the parameter `sampling_period` has been renamed to `input_sampling_period` to better distinguish it from the sampling period parameter in the `resampler_config`.
 
+  * Rename the constructor argument `window_alignment` to `align_to` and change the default to `UNIX_EPOCH`. This is to make it more consistent with the `ResamplerConfig`.
+
 * `Resampler`
 
   * The `ResamplerConfig` now takes the resampling period as a `timedelta`. The configuration was renamed from `resampling_period_s` to `resampling_period` accordingly.

src/frequenz/sdk/timeseries/_moving_window.py

@@ -9,7 +9,7 @@
 import logging
 import math
 from collections.abc import Sequence
-from datetime import datetime, timedelta, timezone
+from datetime import datetime, timedelta
 from typing import SupportsIndex, overload
 
 import numpy as np
@@ -18,6 +18,7 @@
 
 from .._internal.asyncio import cancel_and_await
 from . import Sample
+from ._base_types import UNIX_EPOCH
 from ._resampling import Resampler, ResamplerConfig
 from ._ringbuffer import OrderedRingBuffer
 
@@ -39,9 +40,10 @@ class MovingWindow:
     a fixed defined point in time. Since the moving nature of the window, the
     date of the first and the last element are constantly changing and therefore
     the point in time that defines the alignment can be outside of the time window.
-    Modulo arithmetic is used to move the `window_alignment` timestamp into the
-    latest window.
-    If for example the `window_alignment` parameter is set to
+    Modulo arithmetic is used to move the `align_to` timestamp into the latest
+    window.
+
+    If for example the `align_to` parameter is set to
     `datetime(1, 1, 1, tzinfo=timezone.utc)` and the window size is bigger than
     one day then the first element will always be aligned to the midnight.
     For further information see also the
@@ -106,7 +108,7 @@ def __init__(  # pylint: disable=too-many-arguments
         resampled_data_recv: Receiver[Sample],
         input_sampling_period: timedelta,
         resampler_config: ResamplerConfig | None = None,
-        window_alignment: datetime = datetime(1, 1, 1, tzinfo=timezone.utc),
+        align_to: datetime = UNIX_EPOCH,
     ) -> None:
         """
         Initialize the MovingWindow.
@@ -121,10 +123,9 @@ 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.
-            window_alignment: A datetime object that defines a point in time to which
-                the window is aligned to modulo window size.
-                (default is 0001-01-01T00:00:00+00:00)
-                For further information, consult the class level documentation.
+            align_to: A datetime object that defines a point in time to which
+                the window is aligned to modulo window size. For further
+                information, consult the class level documentation.
 
         Raises:
             asyncio.CancelledError: when the task gets cancelled.
@@ -156,7 +157,7 @@ def __init__(  # pylint: disable=too-many-arguments
         self._buffer = OrderedRingBuffer(
             np.empty(shape=num_samples, dtype=float),
             sampling_period=sampling,
-            time_index_alignment=window_alignment,
+            align_to=align_to,
         )
 
         if self._resampler:

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

@@ -15,6 +15,7 @@
 import numpy.typing as npt
 
 from .. import Sample
+from .._base_types import UNIX_EPOCH
 
 FloatArray = TypeVar("FloatArray", List[float], npt.NDArray[np.float64])
 
@@ -53,19 +54,19 @@ def __init__(
         self,
         buffer: FloatArray,
         sampling_period: timedelta,
-        time_index_alignment: datetime = datetime(1, 1, 1, tzinfo=timezone.utc),
+        align_to: datetime = UNIX_EPOCH,
     ) -> None:
         """Initialize the time aware ringbuffer.
 
         Args:
             buffer: Instance of a buffer container to use internally.
             sampling_period: Timedelta of the desired sampling period.
-            time_index_alignment: Arbitrary point in time used to align
+            align_to: Arbitrary point in time used to align
                 timestamped data with the index position in the buffer.
                 Used to make the data stored in the buffer align with the
                 beginning and end of the buffer borders.
 
-                For example, if the `time_index_alignment` is set to
+                For example, if the `align_to` is set to
                 "0001-01-01 12:00:00", and the `sampling_period` is set to
                 1 hour and the length of the buffer is 24, then the data
                 stored in the buffer could correspond to the time range from
@@ -76,7 +77,7 @@ def __init__(
 
         self._buffer: FloatArray = buffer
         self._sampling_period: timedelta = sampling_period
-        self._time_index_alignment: datetime = time_index_alignment
+        self._time_index_alignment: datetime = align_to
 
         self._gaps: list[Gap] = []
         self._datetime_newest: datetime = self._DATETIME_MIN
@@ -200,7 +201,7 @@ def window(
         * The force_copy parameter was set to True (default False).
 
         The first case can be avoided by using the appropriate
-        time_index_alignment value in the constructor so that the data lines up
+        `align_to` value in the constructor so that the data lines up
         with the start/end of the buffer.
 
         This means, if the caller needs to modify the data to account for

tests/timeseries/test_ringbuffer.py

@@ -266,7 +266,7 @@ def test_len_ringbuffer_samples_fit_buffer_size() -> None:
         buffer = OrderedRingBuffer(
             np.empty(shape=len(test_samples), dtype=float),
             sampling_period=timedelta(seconds=1),
-            time_index_alignment=datetime(1, 1, 1, tzinfo=timezone.utc),
+            align_to=datetime(1, 1, 1, tzinfo=timezone.utc),
         )
 
         start_ts: datetime = datetime(2023, 1, 1, tzinfo=timezone.utc)
@@ -294,7 +294,7 @@ def test_len_ringbuffer_samples_overwrite_buffer() -> None:
         buffer = OrderedRingBuffer(
             np.empty(shape=half_buffer_size, dtype=float),
             sampling_period=timedelta(seconds=1),
-            time_index_alignment=datetime(1, 1, 1, tzinfo=timezone.utc),
+            align_to=datetime(1, 1, 1, tzinfo=timezone.utc),
         )
 
         start_ts: datetime = datetime(2023, 1, 1, tzinfo=timezone.utc)
@@ -316,10 +316,10 @@ def test_ringbuffer_empty_buffer() -> None:
         OrderedRingBuffer(
             empty_np_buffer,
             sampling_period=timedelta(seconds=1),
-            time_index_alignment=datetime(1, 1, 1),
+            align_to=datetime(1, 1, 1),
         )
         OrderedRingBuffer(
             empty_list_buffer,
             sampling_period=timedelta(seconds=1),
-            time_index_alignment=datetime(1, 1, 1),
+            align_to=datetime(1, 1, 1),
         )