waveform: Add frequency spectrum support

src/nitypes/waveform/__init__.py

@@ -65,7 +65,7 @@
 To construct a complex waveform, use the :any:`ComplexWaveform` class:
 
 >>> ComplexWaveform.from_array_1d([1 + 2j, 3 + 4j], np.complex128)
-nitypes.waveform.ComplexWaveform(2, complex128, raw_data=array([1.+2.j, 3.+4.j]))
+nitypes.waveform.ComplexWaveform(2, raw_data=array([1.+2.j, 3.+4.j]))
 
 Scaling complex-number data
 ---------------------------
@@ -84,7 +84,22 @@
 array([(1, 2), (3, 4)], dtype=[('real', '<i2'), ('imag', '<i2')])
 >>> wfm.scaled_data
 array([2.5+4.j, 6.5+8.j])
-"""
+
+Frequency Spectrums
+===================
+
+A frequency spectrum represents an analog signal with frequency information and extended properties
+such as units.
+
+Constructing spectrums
+----------------------
+
+To construct a spectrum, use the :any:`Spectrum` class:
+
+>>> Spectrum.from_array_1d([1, 2, 3], np.float64, start_frequency=100, frequency_increment=10)  # doctest: +NORMALIZE_WHITESPACE
+nitypes.waveform.Spectrum(3, data=array([1., 2., 3.]), start_frequency=100.0,
+    frequency_increment=10.0)
+"""  # noqa: W505 - doc line too long
 
 from nitypes.waveform._analog import AnalogWaveform
 from nitypes.waveform._complex import ComplexWaveform
@@ -100,6 +115,7 @@
     NoneScaleMode,
     ScaleMode,
 )
+from nitypes.waveform._spectrum import Spectrum
 from nitypes.waveform._timing import (
     BaseTiming,
     PrecisionTiming,
@@ -122,6 +138,7 @@
     "SampleIntervalMode",
     "ScaleMode",
     "ScalingMismatchWarning",
+    "Spectrum",
     "Timing",
     "TimingMismatchError",
     "TimingMismatchWarning",
@@ -141,6 +158,7 @@
 SampleIntervalMode.__module__ = __name__
 ScaleMode.__module__ = __name__
 ScalingMismatchWarning.__module__ = __name__
+Spectrum.__module__ = __name__
 Timing.__module__ = __name__
 TimingMismatchError.__module__ = __name__
 TimingMismatchWarning.__module__ = __name__

src/nitypes/waveform/_analog.py

@@ -265,6 +265,7 @@ def __init__(  # noqa: D107 - Missing docstring in __init__ (auto-generated noqa
         start_index: SupportsIndex | None = ...,
         capacity: SupportsIndex | None = ...,
         extended_properties: Mapping[str, ExtendedPropertyValue] | None = ...,
+        copy_extended_properties: bool = ...,
         timing: Timing | PrecisionTiming | None = ...,
         scale_mode: ScaleMode | None = ...,
     ) -> None: ...
@@ -279,6 +280,7 @@ def __init__(  # noqa: D107 - Missing docstring in __init__ (auto-generated noqa
         start_index: SupportsIndex | None = ...,
         capacity: SupportsIndex | None = ...,
         extended_properties: Mapping[str, ExtendedPropertyValue] | None = ...,
+        copy_extended_properties: bool = ...,
         timing: Timing | PrecisionTiming | None = ...,
         scale_mode: ScaleMode | None = ...,
     ) -> None: ...
@@ -293,6 +295,7 @@ def __init__(  # noqa: D107 - Missing docstring in __init__ (auto-generated noqa
         start_index: SupportsIndex | None = ...,
         capacity: SupportsIndex | None = ...,
         extended_properties: Mapping[str, ExtendedPropertyValue] | None = ...,
+        copy_extended_properties: bool = ...,
         timing: Timing | PrecisionTiming | None = ...,
         scale_mode: ScaleMode | None = ...,
     ) -> None: ...
@@ -307,6 +310,7 @@ def __init__(  # noqa: D107 - Missing docstring in __init__ (auto-generated noqa
         start_index: SupportsIndex | None = ...,
         capacity: SupportsIndex | None = ...,
         extended_properties: Mapping[str, ExtendedPropertyValue] | None = ...,
+        copy_extended_properties: bool = ...,
         timing: Timing | PrecisionTiming | None = ...,
         scale_mode: ScaleMode | None = ...,
     ) -> None: ...

src/nitypes/waveform/_complex.py

@@ -253,6 +253,7 @@ def __init__(  # noqa: D107 - Missing docstring in __init__ (auto-generated noqa
         start_index: SupportsIndex | None = ...,
         capacity: SupportsIndex | None = ...,
         extended_properties: Mapping[str, ExtendedPropertyValue] | None = ...,
+        copy_extended_properties: bool = ...,
         timing: Timing | PrecisionTiming | None = ...,
         scale_mode: ScaleMode | None = ...,
     ) -> None: ...
@@ -267,6 +268,7 @@ def __init__(  # noqa: D107 - Missing docstring in __init__ (auto-generated noqa
         start_index: SupportsIndex | None = ...,
         capacity: SupportsIndex | None = ...,
         extended_properties: Mapping[str, ExtendedPropertyValue] | None = ...,
+        copy_extended_properties: bool = ...,
         timing: Timing | PrecisionTiming | None = ...,
         scale_mode: ScaleMode | None = ...,
     ) -> None: ...
@@ -281,6 +283,7 @@ def __init__(  # noqa: D107 - Missing docstring in __init__ (auto-generated noqa
         start_index: SupportsIndex | None = ...,
         capacity: SupportsIndex | None = ...,
         extended_properties: Mapping[str, ExtendedPropertyValue] | None = ...,
+        copy_extended_properties: bool = ...,
         timing: Timing | PrecisionTiming | None = ...,
         scale_mode: ScaleMode | None = ...,
     ) -> None: ...
@@ -295,6 +298,7 @@ def __init__(  # noqa: D107 - Missing docstring in __init__ (auto-generated noqa
         start_index: SupportsIndex | None = ...,
         capacity: SupportsIndex | None = ...,
         extended_properties: Mapping[str, ExtendedPropertyValue] | None = ...,
+        copy_extended_properties: bool = ...,
         timing: Timing | PrecisionTiming | None = ...,
         scale_mode: ScaleMode | None = ...,
     ) -> None: ...

src/nitypes/waveform/_exceptions.py

@@ -1,27 +1,129 @@
 from __future__ import annotations
 
+from typing_extensions import Literal
+
 
 class TimingMismatchError(RuntimeError):
     """Exception used when appending waveforms with mismatched timing."""
 
     pass
 
 
-def input_array_data_type_mismatch(input_dtype: object, waveform_dtype: object) -> TypeError:
-    """Create a TypeError for an input array data type mismatch."""
-    return TypeError(
-        "The data type of the input array must match the waveform data type.\n\n"
-        f"Input array data type: {input_dtype}\n"
-        f"Waveform data type: {waveform_dtype}"
+def capacity_mismatch(capacity: int, array_length: int) -> ValueError:
+    """Create a ValueError for an invalid capacity."""
+    return ValueError(
+        f"The capacity must match the input array length.\n\n"
+        f"Capacity: {capacity}\n"
+        f"Array length: {array_length}"
     )
 
 
-def input_waveform_data_type_mismatch(input_dtype: object, waveform_dtype: object) -> TypeError:
-    """Create a TypeError for an input waveform data type mismatch."""
+def capacity_too_small(capacity: int, min_capacity: int, object_description: str) -> ValueError:
+    """Create a ValueError for an invalid capacity argument."""
+    return ValueError(
+        f"The capacity must be equal to or greater than the number of samples in the {object_description}.\n\n"
+        f"Capacity: {capacity}\n"
+        f"Number of samples: {min_capacity}"
+    )
+
+
+def data_type_mismatch(
+    arg_description: Literal["input array", "input spectrum", "input waveform"],
+    arg_dtype: object,
+    other_description: Literal["requested", "spectrum", "waveform"],
+    other_dtype: object,
+) -> TypeError:
+    """Create a TypeError for a data type mismatch."""
+    arg_key = {
+        "input array": "Input array data type",
+        "input spectrum": "Input spectrum data type",
+        "input waveform": "Input waveform data type",
+    }
+    other_key = {
+        "requested": "Requested data type",
+        "spectrum": "Spectrum data type",
+        "waveform": "Waveform data type",
+    }
     return TypeError(
-        "The data type of the input waveform must match the waveform data type.\n\n"
-        f"Input waveform data type: {input_dtype}\n"
-        f"Waveform data type: {waveform_dtype}"
+        f"The data type of the {arg_description} must match the {other_description} data type.\n\n"
+        f"{arg_key[arg_description]}: {arg_dtype}\n"
+        f"{other_key[other_description]}: {other_dtype}"
+    )
+
+
+def irregular_timestamp_count_mismatch(
+    irregular_timestamp_count: int,
+    other_description: Literal["input array length", "number of samples in the waveform"],
+    other: int,
+    *,
+    reversed: bool = False,
+) -> ValueError:
+    """Create a ValueError for an irregular timestamp count mismatch."""
+    other_key = {
+        "input array length": "Array length",
+        "number of samples in the waveform": "Number of samples",
+    }
+    if reversed:
+        raise ValueError(
+            "The input array length must be equal to the number of irregular timestamps.\n\n"
+            f"{other_key[other_description]}: {other}\n"
+            f"Number of timestamps: {irregular_timestamp_count}"
+        )
+    else:
+        raise ValueError(
+            f"The number of irregular timestamps must be equal to the {other_description}.\n\n"
+            f"Number of timestamps: {irregular_timestamp_count}\n"
+            f"{other_key[other_description]}: {other}"
+        )
+
+
+def start_index_too_large(
+    start_index: int,
+    capacity_description: Literal[
+        "capacity",
+        "input array length",
+        "number of samples in the spectrum",
+        "number of samples in the waveform",
+    ],
+    capacity: int,
+) -> ValueError:
+    """Create a ValueError for an invalid start index argument."""
+    capacity_key = {
+        "capacity": "Capacity",
+        "input array length": "Array length",
+        "number of samples in the spectrum": "Number of samples",
+        "number of samples in the waveform": "Number of samples",
+    }
+    return ValueError(
+        f"The start index must be less than or equal to the {capacity_description}.\n\n"
+        f"Start index: {start_index}\n"
+        f"{capacity_key[capacity_description]}: {capacity}"
+    )
+
+
+def start_index_or_sample_count_too_large(
+    start_index: int,
+    sample_count: int,
+    capacity_description: Literal[
+        "capacity",
+        "input array length",
+        "number of samples in the spectrum",
+        "number of samples in the waveform",
+    ],
+    capacity: int,
+) -> ValueError:
+    """Create a ValueError for an invalid start index or sample count argument."""
+    capacity_key = {
+        "capacity": "Capacity",
+        "input array length": "Array length",
+        "number of samples in the spectrum": "Number of samples",
+        "number of samples in the waveform": "Number of samples",
+    }
+    return ValueError(
+        f"The sum of the start index and sample count must be less than or equal to the {capacity_description}.\n\n"
+        f"Start index: {start_index}\n"
+        f"Sample count: {sample_count}\n"
+        f"{capacity_key[capacity_description]}: {capacity}"
     )