Refactor stream_readers and stream_writers into smaller files (#816)

* stream_readers refactor draft

* cleanup

* cleanup

* stream_writers refactor

* cleanup

* cleanup

---------

Co-authored-by: Mike Prosser <[email protected]>

Author: mikeprosserni

CONTRIBUTING.md

@@ -80,7 +80,7 @@ machine.
 To build the documentation install the optional docs packages and run sphinx. For example:
 
 ```sh
-$ poetry install -E docs
+$ poetry install --with docs
 $ poetry run sphinx-build -b html docs docs\_build
 ```
 

generated/nidaqmx/stream_readers.py

@@ -0,0 +1,33 @@
+"""
+NI-DAQmx stream readers.
+
+This package provides classes for reading samples from NI-DAQmx tasks.
+"""
+
+from __future__ import annotations
+
+from nidaqmx import DaqError
+
+from .analog_single_channel_reader import AnalogSingleChannelReader
+from .analog_multi_channel_reader import AnalogMultiChannelReader
+from .analog_unscaled_reader import AnalogUnscaledReader
+from .counter_reader import CounterReader
+from .digital_single_channel_reader import DigitalSingleChannelReader
+from .digital_multi_channel_reader import DigitalMultiChannelReader
+from .power_readers import (
+    PowerSingleChannelReader,
+    PowerMultiChannelReader,
+    PowerBinaryReader,
+)
+
+__all__ = [
+    'AnalogSingleChannelReader',
+    'AnalogMultiChannelReader',
+    'AnalogUnscaledReader',
+    'CounterReader',
+    'DigitalSingleChannelReader',
+    'DigitalMultiChannelReader',
+    'PowerSingleChannelReader',
+    'PowerMultiChannelReader',
+    'PowerBinaryReader',
+]

generated/nidaqmx/stream_readers/__init__.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from nidaqmx import DaqError
+
+from nidaqmx.error_codes import DAQmxErrors
+
+class ChannelReaderBase:
+    """
+    Defines base class for all NI-DAQmx stream readers.
+    """
+
+    def __init__(self, task_in_stream):
+        """
+        Args:
+            task_in_stream: Specifies the input stream associated with
+                an NI-DAQmx task from which to read samples.
+        """
+        self._in_stream = task_in_stream
+        self._task = task_in_stream._task
+        self._handle = task_in_stream._task._handle
+        self._interpreter = task_in_stream._task._interpreter
+
+        self._verify_array_shape = True
+
+    @property
+    def verify_array_shape(self):
+        """
+        bool: Indicates whether the size and shape of the user-defined
+            NumPy arrays passed to read methods are verified. Defaults
+            to True when this object is instantiated.
+
+            Setting this property to True may marginally adversely
+            impact the performance of read methods.
+        """
+        return self._verify_array_shape
+
+    @verify_array_shape.setter
+    def verify_array_shape(self, val):
+        self._verify_array_shape = val
+
+    def _verify_array(self, data, number_of_samples_per_channel,
+                      is_many_chan, is_many_samp):
+        """
+        Verifies that the shape of the specified NumPy array can be used
+        to read multiple samples from the current task which contains
+        one or more channels, if the "verify_array_shape" property is
+        set to True.
+
+        Args:
+            data (numpy.ndarray): Specifies the NumPy array to verify.
+            number_of_samples_per_channel (int): Specifies the number of
+                samples per channel requested.
+            is_many_chan (bool): Specifies if the read method is a many
+                channel version.
+            is_many_samp (bool): Specifies if the read method is a many
+                samples version.
+        """
+        if not self._verify_array_shape:
+            return
+
+        channels_to_read = self._in_stream.channels_to_read
+        number_of_channels = len(channels_to_read.channel_names)
+
+        array_shape: tuple[int, ...] | None = None
+        if is_many_chan:
+            if is_many_samp:
+                array_shape = (number_of_channels,
+                               number_of_samples_per_channel)
+            else:
+                array_shape = (number_of_channels,)
+        else:
+            if is_many_samp:
+                array_shape = (number_of_samples_per_channel,)
+
+        if array_shape is not None and data.shape != array_shape:
+            raise DaqError(
+                'Read cannot be performed because the NumPy array passed into '
+                'this function is not shaped correctly. You must pass in a '
+                'NumPy array of the correct shape based on the number of '
+                'channels in task and the number of samples per channel '
+                'requested.\n\n'
+                'Shape of NumPy Array provided: {}\n'
+                'Shape of NumPy Array required: {}'
+                .format(data.shape, array_shape),
+                DAQmxErrors.UNKNOWN, task_name=self._task.name)
+
+    def _verify_array_digital_lines(
+            self, data, is_many_chan, is_many_line):
+        """
+        Verifies that the shape of the specified NumPy array can be used
+        to read samples from the current task which contains one or more
+        channels that have one or more digital lines per channel, if the
+        "verify_array_shape" property is set to True.
+
+        Args:
+            data (numpy.ndarray): Specifies the NumPy array to verify.
+            is_many_chan (bool): Specifies if the read method is a
+                many channel version.
+            is_many_line (bool): Specifies if the read method is a
+                many line version.
+        """
+        if not self._verify_array_shape:
+            return
+
+        channels_to_read = self._in_stream.channels_to_read
+        number_of_channels = len(channels_to_read.channel_names)
+        number_of_lines = self._in_stream.di_num_booleans_per_chan
+
+        array_shape: tuple[int, ...] | None = None
+        if is_many_chan:
+            if is_many_line:
+                array_shape = (number_of_channels, number_of_lines)
+            else:
+                array_shape = (number_of_channels,)
+        else:
+            if is_many_line:
+                array_shape = (number_of_lines,)
+
+        if array_shape is not None and data.shape != array_shape:
+            raise DaqError(
+                'Read cannot be performed because the NumPy array passed into '
+                'this function is not shaped correctly. You must pass in a '
+                'NumPy array of the correct shape based on the number of '
+                'channels in task and the number of digital lines per '
+                'channel.\n\n'
+                'Shape of NumPy Array provided: {}\n'
+                'Shape of NumPy Array required: {}'
+                .format(data.shape, array_shape),
+                DAQmxErrors.UNKNOWN, task_name=self._task.name)