Add TimeDeltaArray to bintime

.gitignore

@@ -4,6 +4,7 @@ __pycache__/
 # Unit tests
 .tox/
 test_results/
+.benchmarks/
 
 # Coverage output
 .coverage
@@ -18,4 +19,4 @@ dist/
 docs/_build/
 
 # Common editor metadata
-.vscode/
+.vscode/

CONTRIBUTING.md

@@ -77,6 +77,10 @@ poetry run bandit -c pyproject.toml -r src/nitypes
 poetry run pytest -v
 
 # Run the benchmarks
+#   Compare benchmark before/after a change
+#     see https://pytest-benchmark.readthedocs.io/en/latest/comparing.html
+#   Run 1:  --benchmark-save=some-name
+#   Run N:  --benchmark-compare=0001
 poetry run pytest -v tests/benchmark
 
 # Build and inspect the documentation

src/nitypes/bintime/__init__.py

@@ -24,6 +24,7 @@
 
 * :class:`DateTime`: represents an NI-BTF absolute time as a Python object.
 * :class:`TimeDelta`: represents a NI-BTF time interval as a Python object.
+* :class:`TimeDeltaArray`: an array of :class:`TimeDelta` values.
 
 NI-BTF NumPy Structured Data Types
 ==================================
@@ -74,6 +75,7 @@
 )
 from nitypes.bintime._time_value_tuple import TimeValueTuple
 from nitypes.bintime._timedelta import TimeDelta
+from nitypes.bintime._timedelta_array import TimeDeltaArray
 
 __all__ = [
     "DateTime",
@@ -82,10 +84,12 @@
     "CVITimeIntervalBase",
     "CVITimeIntervalDType",
     "TimeDelta",
+    "TimeDeltaArray",
     "TimeValueTuple",
 ]
 
 # Hide that it was defined in a helper file
 DateTime.__module__ = __name__
 TimeDelta.__module__ = __name__
+TimeDeltaArray.__module__ = __name__
 TimeValueTuple.__module__ = __name__

src/nitypes/bintime/_dtypes.py

@@ -13,4 +13,4 @@
 """Type alias for the base type of :any:`CVITimeIntervalDType`, which is :any:`numpy.void`."""
 
 CVITimeIntervalDType = np.dtype((CVITimeIntervalBase, [("lsb", np.uint64), ("msb", np.int64)]))
-"""NumPy structured data type for a ``CVIAbsoluteTime`` C struct."""
+"""NumPy structured data type for a ``CVITimeInterval`` C struct."""

src/nitypes/bintime/_time_value_tuple.py

@@ -11,3 +11,12 @@ class TimeValueTuple(NamedTuple):
 
     fractional_seconds: int
     """The fractional seconds portion of a binary time value. This should be a uint64."""
+
+    @staticmethod
+    def from_cvi(lsb: int, msb: int) -> TimeValueTuple:
+        """Create a :class:`TimeValueTuple` from a ``CVIAbsoluteTime`` representation."""
+        return TimeValueTuple(whole_seconds=msb, fractional_seconds=lsb)
+
+    def to_cvi(self) -> tuple[int, int]:
+        """Return a representation as ``CVIAbsoluteTime``."""
+        return (self.fractional_seconds, self.whole_seconds)

src/nitypes/bintime/_timedelta_array.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+from collections.abc import Collection, Iterable, MutableSequence
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    final,
+    overload,
+)
+
+import numpy as np
+import numpy.typing as npt
+
+from nitypes._exceptions import invalid_arg_value, invalid_arg_type
+
+if TYPE_CHECKING:
+    # Import from the public package so the docs don't reference private submodules.
+    from nitypes.bintime import CVITimeIntervalDType, TimeDelta, TimeValueTuple
+else:
+    from nitypes.bintime._dtypes import CVITimeIntervalDType
+    from nitypes.bintime._timedelta import TimeDelta
+    from nitypes.bintime._time_value_tuple import TimeValueTuple
+
+
+@final
+class TimeDeltaArray(MutableSequence[TimeDelta]):
+    """A mutable array of :class:`TimeDelta` values in NI Binary Time Format (NI-BTF).
+
+    Raises:
+        TypeError: If any item in value is not a TimeDelta instance.
+    """
+
+    __slots__ = ["_array"]
+
+    _array: npt.NDArray[np.void]
+
+    def __init__(
+        self,
+        value: Collection[TimeDelta] | None = None,
+    ) -> None:
+        """Initialize a new TimeDeltaArray."""
+        if value is None:
+            value = []
+        if not all(isinstance(item, TimeDelta) for item in value):
+            raise invalid_arg_type("value", "iterable of TimeDelta", value)
+        self._array = np.fromiter(
+            (entry.to_tuple().to_cvi() for entry in value),
+            dtype=CVITimeIntervalDType,
+            count=len(value),
+        )
+
+    @overload
+    def __getitem__(  # noqa: D105 - missing docstring in magic method
+        self, index: int
+    ) -> TimeDelta: ...
+
+    @overload
+    def __getitem__(  # noqa: D105 - missing docstring in magic method
+        self, index: slice
+    ) -> TimeDeltaArray: ...
+
+    def __getitem__(self, index: int | slice) -> TimeDelta | TimeDeltaArray:
+        """Return self[index].
+
+        Raises:
+            TypeError: If index is an invalid type.
+            IndexError: If index is out of range.
+        """
+        if isinstance(index, int):
+            entry = self._array[index].item()
+            as_tuple = TimeValueTuple.from_cvi(*entry)
+            return TimeDelta.from_tuple(as_tuple)
+        elif isinstance(index, slice):
+            sliced_entries = self._array[index]
+            new_array = TimeDeltaArray()
+            new_array._array = sliced_entries
+            return new_array
+        else:
+            raise invalid_arg_type("index", "int or slice", index)
+
+    def __len__(self) -> int:
+        """Return len(self)."""
+        return len(self._array)
+
+    @overload
+    def __setitem__(  # noqa: D105 - missing docstring in magic method
+        self, index: int, value: TimeDelta
+    ) -> None: ...
+
+    @overload
+    def __setitem__(  # noqa: D105 - missing docstring in magic method
+        self, index: slice, value: Iterable[TimeDelta]
+    ) -> None: ...
+
+    def __setitem__(self, index: int | slice, value: TimeDelta | Iterable[TimeDelta]) -> None:
+        """Set a new value for TimeDelta at the specified location or slice.
+
+        Raises:
+            TypeError: If index is an invalid type, or slice value is not iterable.
+            ValueError: If slice assignment length doesn't match the selected range.
+            IndexError: If index is out of range.
+        """
+        if isinstance(index, int):
+            if not isinstance(value, TimeDelta):
+                raise invalid_arg_type("value", "TimeDelta", value)
+            self._array[index] = value.to_tuple().to_cvi()
+        elif isinstance(index, slice):
+            if not isinstance(value, Iterable):
+                raise invalid_arg_type("value", "iterable of TimeDelta", value)
+            if not all(isinstance(item, TimeDelta) for item in value):
+                raise invalid_arg_type("value", "iterable of TimeDelta", value)
+
+            start, stop, step = index.indices(len(self))
+            selected_count = len(range(start, stop, step))
+            values = list(value)
+            new_entry_count = len(values)
+            if step > 1 and new_entry_count != selected_count:
+                raise invalid_arg_value(
+                    "value", "iterable with the same length as the slice", value
+                )
+
+            if new_entry_count < selected_count:
+                # Shrink
+                replaced = slice(start, start + new_entry_count)
+                removed = slice(start + new_entry_count, stop)
+                self._array[replaced] = [item.to_tuple().to_cvi() for item in values]
+                del self[removed]
+            elif new_entry_count > selected_count:
+                # Grow
+                replaced = slice(start, stop)
+                self._array[replaced] = [
+                    item.to_tuple().to_cvi() for item in values[:selected_count]
+                ]
+                for offset, entry in enumerate(values[selected_count:]):
+                    self.insert(stop + offset, entry)
+            else:
+                # Replace, accounting for strides
+                self._array[index] = [item.to_tuple().to_cvi() for item in values]
+        else:
+            raise invalid_arg_type("index", "int or slice", index)
+
+    @overload
+    def __delitem__(self, index: int) -> None: ...  # noqa: D105 - missing docstring in magic method
+
+    @overload
+    def __delitem__(  # noqa: D105 - missing docstring in magic method
+        self, index: slice
+    ) -> None: ...
+
+    def __delitem__(self, index: int | slice) -> None:
+        """Delete the value at the specified location or slice.
+
+        Raises:
+            TypeError: If index is an invalid type.
+            IndexError: If index is out of range.
+        """
+        if isinstance(index, (int, slice)):
+            self._array = np.delete(self._array, index)
+        else:
+            raise invalid_arg_type("index", "int or slice", index)
+
+    def insert(self, index: int, value: TimeDelta) -> None:
+        """Insert the TimeDelta value before the specified index.
+
+        Raises:
+            TypeError: If index is not int or value is not TimeDelta.
+        """
+        if not isinstance(index, int):
+            raise invalid_arg_type("index", "int", index)
+        if not isinstance(value, TimeDelta):
+            raise invalid_arg_type("value", "TimeDelta", value)
+        lower = -len(self._array)
+        upper = len(self._array)
+        index = min(max(index, lower), upper)
+        as_cvi = value.to_tuple().to_cvi()
+        self._array = np.insert(self._array, index, as_cvi)
+
+    def __eq__(self, other: object) -> bool:
+        """Return self == other."""
+        if not isinstance(other, TimeDeltaArray):
+            return NotImplemented
+        return np.array_equal(self._array, other._array)
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        """Return object state for pickling."""
+        return (self.__class__, (list(iter(self)),))
+
+    def __repr__(self) -> str:
+        """Return repr(self)."""
+        ctor_args = list(iter(self))
+        return f"{self.__class__.__module__}.{self.__class__.__name__}({ctor_args})"
+
+    def __str__(self) -> str:
+        """Return str(self)."""
+        values = list(iter(self))
+        return f"[{'; '.join(str(v) for v in values)}]"

tests/benchmark/bintime/test_timedelta.py

@@ -9,8 +9,6 @@
 
 import nitypes.bintime as bt
 
-pytestmark = pytest.mark.benchmark
-
 
 @pytest.mark.benchmark(group="timedelta_construct")
 def test___bt_timedelta___construct(

tests/benchmark/bintime/test_timedelta_array.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import numpy as np
+import pytest
+from pytest_benchmark.fixture import BenchmarkFixture
+
+import nitypes.bintime as bt
+
+
+LIST_10: list[bt.TimeDelta] = [bt.TimeDelta(float(value)) for value in np.arange(-10, 10, 0.3)]
+LIST_100: list[bt.TimeDelta] = [bt.TimeDelta(float(value)) for value in np.arange(-100, 100, 0.3)]
+LIST_1000: list[bt.TimeDelta] = [
+    bt.TimeDelta(float(value)) for value in np.arange(-1000, 1000, 0.3)
+]
+LIST_10000: list[bt.TimeDelta] = [
+    bt.TimeDelta(float(value)) for value in np.arange(-10000, 10000, 0.3)
+]
+
+
+@pytest.mark.benchmark(group="timedelta_array_construct", min_rounds=100)
+@pytest.mark.parametrize("constructor_list", (LIST_10, LIST_100, LIST_1000, LIST_10000))
+def test___bt_timedelta_array___construct(
+    benchmark: BenchmarkFixture,
+    constructor_list: list[bt.TimeDelta],
+) -> None:
+    benchmark(bt.TimeDeltaArray, constructor_list)

tests/unit/bintime/test_datetime.py

@@ -14,9 +14,9 @@
 from nitypes.bintime._timedelta import _BITS_PER_SECOND, _FRACTIONAL_SECONDS_MASK
 
 
-#############
+###############################################################################
 # Constructor
-#############
+###############################################################################
 def test___no_args___construct___returns_epoch() -> None:
     value = DateTime()
 
@@ -124,9 +124,9 @@ def test___local_unit_args___construct___raises_value_error() -> None:
     assert exc.value.args[0].startswith("The tzinfo must be datetime.timezone.utc.")
 
 
-############
+###############################################################################
 # from_ticks
-############
+###############################################################################
 def test___int_ticks___from_ticks___returns_time_value() -> None:
     value = DateTime.from_ticks(0x12345678_90ABCDEF_FEDCBA09_87654321)
 
@@ -135,9 +135,9 @@ def test___int_ticks___from_ticks___returns_time_value() -> None:
     assert value._offset._ticks == 0x12345678_90ABCDEF_FEDCBA09_87654321
 
 
-#############
+###############################################################################
 # from_offset
-#############
+###############################################################################
 def test___time_value___from_offset___returns_time_value() -> None:
     value = DateTime.from_offset(TimeDelta.from_ticks(0x12345678_90ABCDEF_FEDCBA09_87654321))
 
@@ -146,9 +146,9 @@ def test___time_value___from_offset___returns_time_value() -> None:
     assert value._offset._ticks == 0x12345678_90ABCDEF_FEDCBA09_87654321
 
 
-##############################################
+###############################################################################
 # year, month, day, hour, minute, second, etc.
-##############################################
+###############################################################################
 @pytest.mark.parametrize(
     "other, expected",
     [
@@ -210,9 +210,9 @@ def test___various_values___unit_properties___return_unit_values(
     ) == expected
 
 
-###################
+###############################################################################
 # Binary arithmetic
-###################
+###############################################################################
 @pytest.mark.parametrize(
     "left, right, expected",
     [
@@ -304,9 +304,9 @@ def test___datetime___sub___returns_time_value(
     assert left - right == expected
 
 
-############
+###############################################################################
 # Comparison
-############
+###############################################################################
 @pytest.mark.parametrize(
     "left, right",
     [
@@ -395,9 +395,9 @@ def test___lesser_value___comparison___lesser(
     assert not (left >= right)
 
 
-###############
+###############################################################################
 # Miscellaneous
-###############
+###############################################################################
 _VARIOUS_VALUES = [
     DateTime(dt.MINYEAR, 1, 1, 0, 0, 0, 0, 0, 0, dt.timezone.utc),
     DateTime(1850, 12, 25, 8, 15, 30, 123_456, 234_567_789, 345_567_890, dt.timezone.utc),