pymodaq_plugins_utils 5.0.3__tar.gz → 5.0.5__tar.gz

{pymodaq_plugins_utils-5.0.3 → pymodaq_plugins_utils-5.0.5}/.github/workflows/Testbase.yml

@@ -18,9 +18,9 @@ jobs:
       QT_DEBUG_PLUGINS: 1
     steps:
       - name: Set up Python ${{ inputs.python }}
-        uses: actions/checkout@v5.0.0
+        uses: actions/checkout@v6.0.3
       - name: Install dependencies
-        uses: actions/setup-python@v6.0.0
+        uses: actions/setup-python@v6.2.0
         with:
           python-version: ${{ inputs.python }}
       - name: Install package

{pymodaq_plugins_utils-5.0.3 → pymodaq_plugins_utils-5.0.5}/.github/workflows/compatibility.yml

@@ -36,10 +36,10 @@ jobs:
           echo "plugin_name=$(echo '${{ github.repository }}' | cut -d'/' -f2)" >> $GITHUB_ENV
 
       - name: Checkout the repo
-        uses: actions/checkout@v5.0.0
+        uses: actions/checkout@v6.0.3
  
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6.0.0
+        uses: actions/setup-python@v6.2.0
         with:
           python-version: ${{ matrix.python-version }}
           
@@ -69,7 +69,7 @@ jobs:
 
       - name: Upload compatibility report
         if: failure()
-        uses: actions/upload-artifact@v4.6.2
+        uses: actions/upload-artifact@v7.0.1
         with:
           name:  
           path: 'import_report_tests_${{ env.plugin_name }}_None.txt'

{pymodaq_plugins_utils-5.0.3 → pymodaq_plugins_utils-5.0.5}/.github/workflows/python-publish.yml

@@ -13,9 +13,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v5.0.0
+    - uses: actions/checkout@v6.0.3
     - name: Set up Python
-      uses: actions/setup-python@v6.0.0
+      uses: actions/setup-python@v6.2.0
       with:
         python-version: '3.13'
     - name: Install dependencies

{pymodaq_plugins_utils-5.0.3 → pymodaq_plugins_utils-5.0.5}/.github/workflows/updater.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v5.0.0
+      - uses: actions/checkout@v6.0.3
         with:
           # [Required] Access token with `workflow` scope.
           token: ${{ secrets.WORKFLOW_SECRET }}

{pymodaq_plugins_utils-5.0.3 → pymodaq_plugins_utils-5.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymodaq_plugins_utils
-Version: 5.0.3
+Version: 5.0.5
 Summary: Set of utility methods and classes to interact with instruments
 Project-URL: Homepage, https://pymodaq.cnrs.fr
 Project-URL: Documentation , https://pymodaq.cnrs.fr
@@ -45,6 +45,7 @@ Classifier: Topic :: Software Development :: User Interfaces
 Requires-Python: >=3.8
 Requires-Dist: pymodaq>=5.0.0
 Provides-Extra: serial
+Requires-Dist: pyserial; extra == 'serial'
 Requires-Dist: pyvisa; extra == 'serial'
 Description-Content-Type: text/x-rst
 

{pymodaq_plugins_utils-5.0.3 → pymodaq_plugins_utils-5.0.5}/pyproject.toml

@@ -11,6 +11,7 @@ package-url = 'https://github.com/PyMoDAQ/pymodaq_plugins_utils'
 [project.optional-dependencies]
 serial = [
     "pyvisa",
+    "pyserial",
 ]
 
 [project]

pymodaq_plugins_utils-5.0.5/src/pymodaq_plugins_utils/hardware/__init__.py

@@ -0,0 +1,33 @@
+"""Hardware discovery caches for PyMoDAQ plugins.
+
+Each backend (:mod:`~pymodaq_utils.hardware.visa`,
+:mod:`~pymodaq_utils.hardware.serial_ports`) queries the OS exactly once per
+process. Subsequent calls reuse the cached result, so plugin startup cost is
+paid at most once regardless of how many plugins share the same backend.
+
+Quick reference::
+
+    # VISA-based plugin (Newport, Thorlabs, PI, ...)
+    from pymodaq_utils.hardware.visa import list_serial_resources
+    ports = list_serial_resources()
+
+    # pyserial-based plugin (Arduino, Ocean Optics, ...)
+    from pymodaq_utils.hardware.serial_ports import list_resources
+    ports = list_resources()
+
+    # After hot-plugging a device
+    from pymodaq_utils.hardware import invalidate_all_caches
+    invalidate_all_caches()
+"""
+from .visa import invalidate_cache as _invalidate_visa
+from .serial_ports import invalidate_cache as _invalidate_serial
+
+
+def invalidate_all_caches() -> None:
+    """Clear both the VISA and serial discovery caches.
+
+    Call this after hot-plugging a device so the next call to any
+    ``list_*`` function re-discovers the current set of instruments.
+    """
+    _invalidate_visa()
+    _invalidate_serial()

pymodaq_plugins_utils-5.0.5/src/pymodaq_plugins_utils/hardware/base.py

@@ -0,0 +1,59 @@
+
+class HardwareCache:
+    """Base class for process-lifetime hardware discovery caches.
+
+    Each subclass calls its backend (pyvisa, pyserial, …) exactly once per
+    process. The result is stored as a class variable and reused by every
+    caller, regardless of which plugin package triggered the first call.
+
+    Subclasses must override :meth:`_fetch` and :meth:`list_resources`.
+    Call :meth:`invalidate_cache` to force re-discovery, for example after
+    hot-plugging a device.
+
+    Example — defining a new backend::
+
+        class MyCache(HardwareCache):
+            _cache = None
+
+            @classmethod
+            def _fetch(cls):
+                return some_expensive_os_call()
+
+            @classmethod
+            def list_resources(cls) -> list[str]:
+                return [item.id for item in cls._get_cache()]
+    """
+
+    _cache = None
+
+    @classmethod
+    def _fetch(cls):
+        """Perform the actual hardware discovery.
+
+        Called at most once per process. Must return a value that can be
+        stored and reused (list, dict, …). Should catch all exceptions and
+        return an empty container so that callers never need to guard against
+        missing backends.
+        """
+        raise NotImplementedError
+
+    @classmethod
+    def _get_cache(cls):
+        """Return the cached discovery result, populating it on first call."""
+        if cls._cache is None:
+            cls._cache = cls._fetch()
+        return cls._cache
+
+    @classmethod
+    def invalidate_cache(cls) -> None:
+        """Clear the cache so the next call to any list_* method re-discovers.
+
+        Use this after hot-plugging a device or when the set of available
+        instruments may have changed since process startup.
+        """
+        cls._cache = None
+
+    @classmethod
+    def list_resources(cls) -> list[str]:
+        """Return a list of connectable resource strings for this backend."""
+        raise NotImplementedError

{pymodaq_plugins_utils-5.0.3 → pymodaq_plugins_utils-5.0.5}/src/pymodaq_plugins_utils/hardware/camera_base_pylablib.py

@@ -1,4 +1,9 @@
+import dataclasses
+from typing import Type
+
 import cv2
+
+from pymodaq_data import DataToExport
 from pymodaq_utils.logger import set_logger, get_module_name
 from pymodaq_utils.utils import ThreadCommand
 from pymodaq_gui.parameter import Parameter
@@ -10,15 +15,20 @@ except ImportError:
 from pymodaq.utils.data import DataFromPlugins, Axis
 from pymodaq.control_modules.viewer_utility_classes import DAQ_Viewer_base, comon_parameters, main
 
+from pylablib.devices.interface.camera import trim_frames
+
 from qtpy import QtWidgets, QtCore
 import numpy as np
 from time import perf_counter
 
 
+logger = set_logger(get_module_name(__file__))
+
+
 cam_params = [
     {'title': 'Camera name:', 'name': 'camera_name', 'type': 'str', 'value': '', 'readonly': True},
-    {'title': 'Sensor type:', 'name': 'sensor', 'type': 'list', 'limits': ['Monochrome', 'Bayer']},
-    {'title': 'Ouput Color:', 'name': 'output_color', 'type': 'list', 'limits': ['RGB', 'MonoChrome']},
+    {'title': 'Color Conversion:', 'name': 'color_conversion', 'type': 'list',
+     'limits': ['None', 'RGB2GRAY', 'BAYER_BG2RGB', 'BAYER_BG2GRAY']},
     {'title': 'ROI', 'name': 'roi', 'type': 'group', 'children': [
         {'title': 'Update ROI from Viewer', 'name': 'update_roi', 'type': 'led', 'value': False},
         {'title': 'Apply ROI', 'name': 'apply_roi', 'type': 'led', 'value': False},
@@ -42,6 +52,60 @@ cam_params = [
 ]
 
 
+@dataclasses.dataclass
+class Grab:
+    do_acquisition: bool = True
+    snap: bool = False
+    since: str = 'now'
+    nframes: int = 1
+    n_average: int = 1
+
+
+class CameraCallback(QtCore.QObject):
+    """Callback object """
+    data_sig = QtCore.Signal(np.ndarray)
+    error = QtCore.Signal()
+
+    def __init__(self, controller):
+        super().__init__()
+        # Set the wait function
+        self.controller = controller
+        self.do_acquisition = True
+
+    def set_do_grab(self, mode: Grab):
+        self.do_acquisition = mode.do_acquisition
+        if mode.do_acquisition:
+            self.wait_for_acquisition(mode)
+
+    def wait_for_acquisition(self, mode: Grab):
+        while self.do_acquisition:
+            try:
+                ind_average = 0
+                while ind_average < mode.n_average:
+                    ind_frames = 0
+                    while ind_frames < mode.nframes:
+                        self.controller.wait_for_frame(since='now')
+                        new_frames, rng = self.controller.read_multiple_images(missing_frame='skip', return_rng=True)
+                        if ind_average == 0 and ind_frames == 0:
+                            shape = list(new_frames.shape[1:])
+                            shape = [mode.n_average, mode.nframes] + shape
+                            frames = np.zeros(shape, dtype=new_frames.dtype)
+                        nacq = rng[1] - rng[0]
+                        frames[ind_average, ind_frames:nacq, ...] = new_frames
+                        ind_frames += nacq
+                    ind_average += 1
+                self.data_sig.emit(frames)
+                QtCore.QThread.msleep(10)
+            except Exception as e:
+                logger.exception(str(e))
+                self.error.emit()
+                break
+            QtWidgets.QApplication.processEvents()
+            if not self.do_acquisition or mode.snap:
+                break
+
+
+
 class CameraBasePyLabLib(DAQ_Viewer_base):
     """
     Base implementation for Camera using pylablib framework. Works for TSI and uc480 thorlabs camera and rpobaly others
@@ -52,13 +116,15 @@ class CameraBasePyLabLib(DAQ_Viewer_base):
 
     params = comon_parameters + serial_params + cam_params
 
-    callback_signal = QtCore.Signal(bool)
+    callback_signal = QtCore.Signal(Grab)
     live_mode_available = True
-
+    hardware_averaging = True
 
     def ini_attributes(self):
         self.controller = None
         self.callback_thread: QtCore.QThread = None
+        self.is_live: bool = False
+        self.Naverage: int = 1
 
         self.x_axis: Axis = None
         self.y_axis: Axis = None
@@ -135,16 +201,16 @@ class CameraBasePyLabLib(DAQ_Viewer_base):
         if param.name() == "exposure_time":
             self.controller.set_exposure(param.value()/1000)
 
-        if param.name() == "fps_on":
+        elif param.name() == "fps_on":
             self.settings.child('timing_opts', 'fps').setOpts(visible=param.value())
 
-        if param.name() == "apply_roi":
+        elif param.name() == "apply_roi":
             if param.value():   # Switching on ROI
                 self.apply_roi()
             else:
                 self.clear_roi()
 
-        if param.name() in ['x_binning', 'y_binning']:
+        elif param.name() in ['x_binning', 'y_binning']:
             # We handle ROI and binning separately for clarity
             (x0, w, y0, h, *_) = self.controller.get_roi()  # Get current ROI
             xbin = self.settings['roi', 'x_binning']
@@ -152,14 +218,11 @@ class CameraBasePyLabLib(DAQ_Viewer_base):
             new_roi = (x0, w, xbin, y0, h, ybin)
             self.update_rois(new_roi)
 
-        if param.name() == "clear_roi":
+        elif param.name() == "clear_roi":
             if param.value():   # Switching on ROI
                 self.clear_roi()
                 param.setValue(False)
 
-        if param.name() == 'sensor':
-            self.get_set_color()
-
     def ini_detector_custom(self, controller=None):
         raise NotImplementedError
 
@@ -178,12 +241,13 @@ class CameraBasePyLabLib(DAQ_Viewer_base):
         initialized: bool
             False if initialization failed otherwise True
         """
+
         self.ini_detector_custom(controller)
 
         self.get_device_info()
-        self.get_set_color()
         self.get_set_main_parameters()
         self.setup_callback_thread()
+        self.controller.set_frame_format("array")
 
         info = "Initialized camera"
         initialized = True
@@ -199,13 +263,6 @@ class CameraBasePyLabLib(DAQ_Viewer_base):
         elif hasattr(device_info, 'model'):
             self.settings.child('camera_name').setValue(device_info.model)
 
-    def get_set_color(self):
-        if 'monochrome' in self.settings['sensor'].lower():
-            self.settings.child('output_color').setValue('MonoChrome')
-            self.settings.child('output_color').setOpts(visible=False)
-        else:
-            self.settings.child('output_color').setOpts(visible=True)
-
     def get_set_main_parameters(self):
         # Set exposure time
         self.controller.set_exposure(self.settings['timing_opts', 'exposure_time']/1000)
@@ -227,18 +284,28 @@ class CameraBasePyLabLib(DAQ_Viewer_base):
         self.settings.child('roi', 'roi_slices').setValue(str(slices))
         self.compute_axes()
 
+    @property
+    def callback(self) -> Type[CameraCallback]:
+        """ Return the class handling the wait for acquisition and signal emission
+
+        Should be reimplement as well as CameraCallback if needed
+        """
+        return CameraCallback
+
     def setup_callback_thread(self):
         # Way to define a wait function with arguments
         wait_func = lambda: self.controller.wait_for_frame(since=self.settings['buffer', 'mode'],
                                                            nframes=1, timeout=20.0)
-        callback = CameraCallback(wait_func)
+        callback = CameraCallback(self.controller)
         self.settings.child('buffer', 'mode').setReadonly(True)
 
 
         self.callback_thread = QtCore.QThread()  # creation of a Qt5 thread
         callback.moveToThread(self.callback_thread)  # callback object will live within this thread
+
         callback.data_sig.connect(
             self.emit_data)  # when the wait for acquisition returns (with data taken), emit_data will be fired
+        callback.error.connect(self.handle_error)
 
         self.callback_signal.connect(callback.set_do_grab)
         self.callback_thread.callback = callback
@@ -246,6 +313,8 @@ class CameraBasePyLabLib(DAQ_Viewer_base):
 
         self._prepare_view()
 
+    def handle_error(self):
+        self.stop()
 
     def _prepare_view(self):
         """Preparing a data viewer by emitting temporary data. Typically, needs to be called whenever the
@@ -280,14 +349,20 @@ class CameraBasePyLabLib(DAQ_Viewer_base):
         """
         try:
             # Warning, acquisition_in_progress returns 1,0 and not a real bool
-            if not kwargs.get('live', False):
-                self.emit_data(self.controller.snap())
-            else:
-                if not self.controller.acquisition_in_progress():
-                    self.controller.clear_acquisition()
-                    self.controller.start_acquisition(nframes=self.settings['buffer', 'size'])
-                #Then start the acquisition
-                self.callback_signal.emit(True)  # will trigger the wait for acquisition
+            self.is_live = kwargs.get('live', False)
+            self.Naverage = Naverage
+
+            self.n_frames = 1
+
+            if not self.controller.acquisition_in_progress():
+                self.controller.clear_acquisition()
+                self.controller.start_acquisition(nframes=self.n_frames)
+            #Then start the acquisition
+            self.callback_signal.emit(Grab(do_acquisition=True,
+                                           snap=not self.is_live,
+                                           n_average=Naverage,
+                                           nframes=self.n_frames,
+                                           since=self.settings['buffer', 'mode']))
 
         except Exception as e:
             self.emit_status(ThreadCommand('Update_Status', [str(e), "log"]))
@@ -309,21 +384,48 @@ class CameraBasePyLabLib(DAQ_Viewer_base):
             if frame is None:
                 frame = self.controller.read_newest_image()
             # Emit the frame.
-            if frame is not None:       # happens for last frame when stopping camera
-                if self.settings['output_color'] == 'RGB':
-                    rgb_image = cv2.cvtColor(frame, cv2.COLOR_BAYER_BG2RGB)
-                    data_arrays = [np.atleast_1d(rgb_image[..., ind]) for ind in range(3)]
+            if frame is not None:
+                conversion_str = self.settings['color_conversion']
+                if conversion_str != "None":
+                    for ind_average in range(frame.shape[0]):
+                        for ind_frame in range(frame.shape[1]):
+                            if ind_frame == 0 and ind_average == 0:
+                                new_frame = cv2.cvtColor(frame[ind_average, ind_frame, ...],
+                                                         getattr(cv2, f'COLOR_{conversion_str}'))
+                                shape = [frame.shape[0], frame.shape[1]] + list(new_frame.shape)
+                                out_frames = np.zeros(shape, dtype=new_frame.dtype)
+                                out_frames[ind_average, ind_frame, ...] = new_frame
+                            else:
+                                cv2.cvtColor(frame[ind_average, ind_frame, ...],
+                                             getattr(cv2, f'COLOR_{conversion_str}'),
+                                             out_frames[ind_average, ind_frame, ...])
+                else:
+                    out_frames = frame
+                if self.Naverage > 1:
+                    out_frames = np.sum(out_frames, axis=0) / self.Naverage
+                else:
+                    out_frames = out_frames[0, ...]
+
+                if self.n_frames > 1:
+                    pass
+                    #todo handle chunks of frames in ND data
+                else:
+                    out_frames = out_frames[0, ...]
+
+                if out_frames.shape[-1] == 3:
+                    data_arrays = [np.atleast_1d(out_frames[..., ind]) for ind in range(3)]
+                    labels = ['Red', 'Green', 'Blue']
                 else:
-                    if 'monochrome' in self.settings['sensor'].lower():
-                        data_arrays = [np.atleast_1d(frame)]
-                    else:
-                        data_arrays = [np.atleast_1d(cv2.cvtColor(frame, cv2.COLOR_BAYER_BG2GRAY))]
-
-                self.data_grabed_signal.emit([DataFromPlugins(name='Thorlabs Camera',
-                                                              data=data_arrays,
-                                                              dim=self.data_shape,
-                                                              labels=[f'ThorCam_{self.data_shape}'],
-                                                              axes=[self.x_axis, self.y_axis])])
+                    labels = ['Intensity']
+                    data_arrays = [out_frames]
+
+                self.dte_signal.emit(
+                    DataToExport('Camera',
+                                 data=[DataFromPlugins(name='Camera',
+                                                       data=data_arrays,
+                                                       dim=self.data_shape,
+                                                       labels=labels,
+                                                       axes=[self.y_axis, self.x_axis])]))
             if self.settings.child('timing_opts', 'fps_on').value():
                 self.update_fps()
 
@@ -367,37 +469,11 @@ class CameraBasePyLabLib(DAQ_Viewer_base):
 
     def stop(self):
         """Stop the acquisition."""
-        self.callback_signal.emit(False)
+        self.callback_signal.emit(Grab(do_acquisition=False))
         QtWidgets.QApplication.processEvents()
-
         self.controller.clear_acquisition()
         return ''
 
 
-class CameraCallback(QtCore.QObject):
-    """Callback object """
-    data_sig = QtCore.Signal()
-
-    def __init__(self, wait_fn):
-        super().__init__()
-        # Set the wait function
-        self.wait_fn = wait_fn
-        self.do_grab = True
-
-    def set_do_grab(self, do_grab=True):
-        self.do_grab = do_grab
-        if do_grab:
-            self.wait_for_acquisition()
-
-    def wait_for_acquisition(self):
-        while self.do_grab:
-            try:
-                new_data = self.wait_fn()
-                if new_data is not False:  # will be returned if the main thread called CancelWait
-                    self.data_sig.emit()
-            except Exception as e:
-                pass
-            QtWidgets.QApplication.processEvents()
-
 
 

pymodaq_plugins_utils-5.0.5/src/pymodaq_plugins_utils/hardware/serial_ports.py

@@ -0,0 +1,63 @@
+"""pyserial hardware discovery cache.
+
+Wraps :mod:`serial.tools.list_ports` to enumerate available serial ports
+exactly once per process. ``pyserial`` is an optional dependency: if it is
+not installed, all functions return empty lists and a warning is logged.
+
+Typical usage in a plugin::
+
+    from pymodaq_utils.hardware.serial_ports import list_resources
+
+    ports = list_resources()  # e.g. ['/dev/ttyUSB0', 'COM3']
+
+After hot-plugging a device, refresh the cache with::
+
+    from pymodaq_utils.hardware.serial_ports import invalidate_cache
+    invalidate_cache()
+"""
+import pymodaq_utils.logger as logger_module
+from .base import HardwareCache
+
+logger = logger_module.set_logger(logger_module.get_module_name(__file__))
+
+
+class SerialPortsCache(HardwareCache):
+    _cache = None
+
+    @classmethod
+    def _fetch(cls) -> list:
+        try:
+            from serial.tools.list_ports import comports
+            return list(comports())
+        except ImportError:
+            logger.warning('pyserial is not installed — serial port discovery unavailable. '
+                           'Install it with: pip install pyserial')
+            return []
+        except Exception as e:
+            logger.warning(f'Serial port discovery failed: {e}')
+            return []
+
+    @classmethod
+    def list_resources(cls) -> list[str]:
+        """Serial port device strings (e.g. '/dev/ttyUSB0', 'COM3')."""
+        return [p.device for p in cls._get_cache()]
+
+    @classmethod
+    def list_port_descriptions(cls) -> list[str]:
+        """Human-readable descriptions for each serial port."""
+        return [p.description for p in cls._get_cache()]
+
+
+def list_resources() -> list[str]:
+    """Serial port device strings (e.g. '/dev/ttyUSB0', 'COM3')."""
+    return SerialPortsCache.list_resources()
+
+
+def list_port_descriptions() -> list[str]:
+    """Human-readable descriptions for each serial port."""
+    return SerialPortsCache.list_port_descriptions()
+
+
+def invalidate_cache() -> None:
+    """Clear the serial port cache so the next call re-discovers."""
+    SerialPortsCache.invalidate_cache()

pymodaq_plugins_utils-5.0.5/src/pymodaq_plugins_utils/hardware/visa.py

@@ -0,0 +1,84 @@
+"""VISA hardware discovery cache.
+
+Wraps :mod:`pyvisa` to enumerate available VISA resources exactly once per
+process. ``pyvisa`` is an optional dependency: if it is not installed, or no
+VISA backend is found, all functions return empty lists and a warning is logged.
+
+Typical usage in a plugin::
+
+    from pymodaq_utils.hardware.visa import list_serial_resources
+
+    ports = list_serial_resources()  # e.g. ['ASRL/dev/ttyUSB0::INSTR']
+
+After hot-plugging a device, refresh the cache with::
+
+    from pymodaq_utils.hardware.visa import invalidate_cache
+    invalidate_cache()
+"""
+import pymodaq_utils.logger as logger_module
+from .base import HardwareCache
+
+logger = logger_module.set_logger(logger_module.get_module_name(__file__))
+
+
+class VisaCache(HardwareCache):
+    _cache = None
+
+    @classmethod
+    def _fetch(cls) -> dict:
+        try:
+            import pyvisa
+            rm = pyvisa.ResourceManager()
+            info = dict(rm.list_resources_info())
+            rm.close()
+            return info
+        except ImportError:
+            logger.warning('pyvisa is not installed — VISA resource discovery unavailable. '
+                           'Install it with: pip install pyvisa pyvisa-py')
+            return {}
+        except Exception as e:
+            logger.warning(f'VISA resource discovery failed: {e}')
+            return {}
+
+    @classmethod
+    def list_resources(cls) -> list[str]:
+        """All available VISA resource strings (e.g. 'GPIB0::5::INSTR')."""
+        return list(cls._get_cache().keys())
+
+    @classmethod
+    def list_serial_resources(cls) -> list[str]:
+        """ASRL (serial-over-VISA) resource strings only.
+
+        Linux:   'ASRL/dev/ttyUSB0::INSTR'
+        Windows: 'ASRL3::INSTR'
+        """
+        return [r for r in cls._get_cache() if r.startswith('ASRL')]
+
+    @classmethod
+    def list_resource_aliases(cls) -> list[str]:
+        """Human-readable aliases where available (e.g. 'COM3' on Windows)."""
+        return [i.alias for i in cls._get_cache().values() if i.alias]
+
+
+def list_resources() -> list[str]:
+    """All available VISA resource strings (e.g. 'GPIB0::5::INSTR', 'TCPIP0::...')."""
+    return VisaCache.list_resources()
+
+
+def list_serial_resources() -> list[str]:
+    """ASRL (serial-over-VISA) resource strings only.
+
+    Linux:   ``'ASRL/dev/ttyUSB0::INSTR'``
+    Windows: ``'ASRL3::INSTR'``
+    """
+    return VisaCache.list_serial_resources()
+
+
+def list_resource_aliases() -> list[str]:
+    """Human-readable aliases where available (e.g. ``'COM3'`` on Windows)."""
+    return VisaCache.list_resource_aliases()
+
+
+def invalidate_cache() -> None:
+    """Clear the VISA resource cache so the next call re-discovers."""
+    VisaCache.invalidate_cache()

pymodaq_plugins_utils-5.0.5/tests/hardware_test.py

@@ -0,0 +1,249 @@
+import pytest
+
+from pymodaq_plugins_utils.hardware.base import HardwareCache
+from pymodaq_plugins_utils.hardware import visa, serial_ports, invalidate_all_caches
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+class _CountingCache(HardwareCache):
+    """Minimal concrete subclass used to test base-class caching logic."""
+    _cache = None
+    fetch_count = 0
+
+    @classmethod
+    def _fetch(cls):
+        cls.fetch_count += 1
+        return ['resource_a', 'resource_b']
+
+    @classmethod
+    def list_resources(cls):
+        return list(cls._get_cache())
+
+    @classmethod
+    def reset(cls):
+        cls._cache = None
+        cls.fetch_count = 0
+
+
+# ---------------------------------------------------------------------------
+# HardwareCache base behaviour
+# ---------------------------------------------------------------------------
+
+class TestHardwareCacheBase:
+
+    def setup_method(self):
+        _CountingCache.reset()
+
+    def test_fetch_called_once(self):
+        # Core guarantee: no matter how many times list_resources() is called,
+        # the expensive OS-level _fetch() runs exactly once per process lifetime.
+        _CountingCache.list_resources()
+        _CountingCache.list_resources()
+        assert _CountingCache.fetch_count == 1
+
+    def test_returns_correct_data(self):
+        assert _CountingCache.list_resources() == ['resource_a', 'resource_b']
+
+    def test_invalidate_triggers_refetch(self):
+        # After invalidation the cache is empty, so the next call must
+        # re-run _fetch() — this is the hot-plug refresh path.
+        _CountingCache.list_resources()
+        _CountingCache.invalidate_cache()
+        _CountingCache.list_resources()
+        assert _CountingCache.fetch_count == 2
+
+    def test_cache_is_none_after_invalidate(self):
+        # Validates the internal reset so _get_cache() knows to call _fetch()
+        # again on the next access (tested separately in test_invalidate_triggers_refetch).
+        _CountingCache.list_resources()
+        _CountingCache.invalidate_cache()
+        assert _CountingCache._cache is None
+
+    def test_subclasses_have_independent_caches(self):
+        # Each subclass stores its result in its own _cache class variable.
+        # Invalidating one must not affect the other — otherwise a Newport
+        # plugin resetting its cache would silently clear an Arduino plugin's cache.
+        class CacheA(HardwareCache):
+            _cache = None
+
+            @classmethod
+            def _fetch(cls):
+                return ['a']
+
+            @classmethod
+            def list_resources(cls):
+                return list(cls._get_cache())
+
+        class CacheB(HardwareCache):
+            _cache = None
+
+            @classmethod
+            def _fetch(cls):
+                return ['b']
+
+            @classmethod
+            def list_resources(cls):
+                return list(cls._get_cache())
+
+        assert CacheA.list_resources() == ['a']
+        assert CacheB.list_resources() == ['b']
+        CacheA.invalidate_cache()
+        assert CacheA._cache is None
+        assert CacheB._cache is not None  # CacheB untouched
+
+
+# ---------------------------------------------------------------------------
+# visa module
+# ---------------------------------------------------------------------------
+
+class TestVisaModule:
+
+    def setup_method(self):
+        # Start each test with a clean cache so tests are isolated.
+        visa.VisaCache.invalidate_cache()
+
+    def test_list_resources_returns_list(self):
+        # The module must never raise, even when pyvisa is not installed.
+        assert isinstance(visa.list_resources(), list)
+
+    def test_warns_when_pyvisa_absent(self, monkeypatch):
+        # When pyvisa is missing the user should get an explicit warning,
+        # not a silent empty list that looks like "no devices connected".
+        import builtins
+        real_import = builtins.__import__
+
+        def block_pyvisa(name, *args, **kwargs):
+            if name == 'pyvisa':
+                raise ImportError('pyvisa blocked for test')
+            return real_import(name, *args, **kwargs)
+
+        warned = []
+        monkeypatch.setattr(builtins, '__import__', block_pyvisa)
+        monkeypatch.setattr(visa.logger, 'warning', lambda msg: warned.append(msg))
+        visa.VisaCache.invalidate_cache()
+
+        visa.list_resources()
+        assert any('pyvisa' in msg for msg in warned)
+
+    def test_list_serial_resources_returns_list(self):
+        assert isinstance(visa.list_serial_resources(), list)
+
+    def test_list_resource_aliases_returns_list(self):
+        assert isinstance(visa.list_resource_aliases(), list)
+
+    def test_serial_resources_are_subset_of_all(self):
+        # list_serial_resources() is a filtered view of list_resources();
+        # every ASRL entry must also appear in the full resource list.
+        # Skipped when pyvisa is absent: an empty list would make this pass
+        # vacuously without testing anything.
+        pytest.importorskip('pyvisa')
+        all_r = visa.list_resources()
+        serial_r = visa.list_serial_resources()
+        assert all(r in all_r for r in serial_r)
+
+    def test_serial_resources_start_with_asrl(self):
+        # VISA serial resources always begin with 'ASRL' by the VISA standard.
+        # Skipped when pyvisa is absent for the same reason as above.
+        pytest.importorskip('pyvisa')
+        for r in visa.list_serial_resources():
+            assert r.startswith('ASRL')
+
+    def test_fetch_called_once_across_multiple_functions(self, monkeypatch):
+        # Calling list_resources(), list_serial_resources(), and
+        # list_resource_aliases() in sequence must trigger only one backend
+        # query — the whole point of this module.
+        call_count = []
+        original_fetch = visa.VisaCache._fetch.__func__
+
+        @classmethod
+        def counting_fetch(cls):
+            call_count.append(1)
+            return original_fetch(cls)
+
+        monkeypatch.setattr(visa.VisaCache, '_fetch', counting_fetch)
+        visa.VisaCache.invalidate_cache()
+
+        visa.list_resources()
+        visa.list_serial_resources()
+        visa.list_resource_aliases()
+
+        assert len(call_count) == 1
+
+
+# ---------------------------------------------------------------------------
+# serial_ports module
+# ---------------------------------------------------------------------------
+
+class TestSerialPortsModule:
+
+    def setup_method(self):
+        serial_ports.SerialPortsCache.invalidate_cache()
+
+    def test_list_resources_returns_list(self):
+        # The module must never raise, even when pyserial is not installed.
+        assert isinstance(serial_ports.list_resources(), list)
+
+    def test_warns_when_pyserial_absent(self, monkeypatch):
+        # Same contract as the visa equivalent: missing backend → warning, not silent empty list.
+        import builtins
+        real_import = builtins.__import__
+
+        def block_serial(name, *args, **kwargs):
+            if name == 'serial.tools.list_ports':
+                raise ImportError('pyserial blocked for test')
+            return real_import(name, *args, **kwargs)
+
+        warned = []
+        monkeypatch.setattr(builtins, '__import__', block_serial)
+        monkeypatch.setattr(serial_ports.logger, 'warning', lambda msg: warned.append(msg))
+        serial_ports.SerialPortsCache.invalidate_cache()
+
+        serial_ports.list_resources()
+        assert any('pyserial' in msg for msg in warned)
+
+    def test_list_port_descriptions_returns_list(self):
+        assert isinstance(serial_ports.list_port_descriptions(), list)
+
+    def test_resources_and_descriptions_same_length(self):
+        # Both lists are derived from the same cached port objects, so they
+        # must always be parallel (index N in one matches index N in the other).
+        # Skipped when pyserial is absent: both would be empty and the assertion
+        # passes vacuously without testing anything.
+        pytest.importorskip('serial')
+        assert len(serial_ports.list_resources()) == len(serial_ports.list_port_descriptions())
+
+    def test_fetch_called_once_across_multiple_functions(self, monkeypatch):
+        # Same single-fetch guarantee as the visa module.
+        call_count = []
+        original_fetch = serial_ports.SerialPortsCache._fetch.__func__
+
+        @classmethod
+        def counting_fetch(cls):
+            call_count.append(1)
+            return original_fetch(cls)
+
+        monkeypatch.setattr(serial_ports.SerialPortsCache, '_fetch', counting_fetch)
+        serial_ports.SerialPortsCache.invalidate_cache()
+
+        serial_ports.list_resources()
+        serial_ports.list_port_descriptions()
+
+        assert len(call_count) == 1
+
+
+# ---------------------------------------------------------------------------
+# Package-level helper
+# ---------------------------------------------------------------------------
+
+def test_invalidate_all_caches_clears_both():
+    # Populate both caches first so the assertion is meaningful.
+    visa.list_resources()
+    serial_ports.list_resources()
+
+    invalidate_all_caches()
+
+    assert visa.VisaCache._cache is None
+    assert serial_ports.SerialPortsCache._cache is None