syndesi 0.4.1__py3-none-any.whl → 0.4.4__py3-none-any.whl

syndesi/__init__.py

@@ -1,5 +1,10 @@
+"""
+Syndesi module
+"""
+
 from .adapters.ip import IP
 from .adapters.serialport import SerialPort
+from .adapters.timeout import Timeout
 from .adapters.visa import Visa
 from .protocols.delimited import Delimited
 from .protocols.modbus import Modbus
@@ -7,4 +12,14 @@ from .protocols.raw import Raw
 from .protocols.scpi import SCPI
 from .tools.log import log
 
-__all__ = ["IP", "SerialPort", "Visa", "Delimited", "Modbus", "Raw", "SCPI", "log"]
+__all__ = [
+    "IP",
+    "SerialPort",
+    "Visa",
+    "Delimited",
+    "Modbus",
+    "Raw",
+    "SCPI",
+    "log",
+    "Timeout",
+]

syndesi/adapters/adapter.py

@@ -1,22 +1,24 @@
 # File : adapters.py
 # Author : Sébastien Deriaz
 # License : GPL
-#
-# Adapters provide a common abstraction for the media layers (physical + data link + network)
-# The following classes are provided, which all are derived from the main Adapter class
-#   - IP
-#   - Serial
-#   - VISA
-#
-# Note that technically VISA is not part of the media layer, only USB is.
-# This is a limitation as it is to this day not possible to communicate "raw"
-# with a device through USB yet
-#
-# An adapter is meant to work with bytes objects but it can accept strings.
-# Strings will automatically be converted to bytes using utf-8 encoding
 
-from enum import Enum
+"""
+Adapters provide a common abstraction for the media layers (physical + data link + network)
+The following classes are provided, which all are derived from the main Adapter class
+  - IP
+  - Serial
+  - VISA
+
+Note that technically VISA is not part of the media layer, only USB is.
+This is a limitation as it is to this day not possible to communicate "raw"
+with a device through USB yet
+
+An adapter is meant to work with bytes objects but it can accept strings.
+Strings will automatically be converted to bytes using utf-8 encoding
+"""
+
 import logging
+import os
 import queue
 import subprocess
 import sys
@@ -25,93 +27,125 @@ import time
 import weakref
 from abc import ABC, abstractmethod
 from collections.abc import Callable
+from enum import Enum
 from multiprocessing.connection import Client, Connection
 from types import EllipsisType
 from typing import Any
-import os
 
-from .backend.backend_tools import BACKEND_REQUEST_DEFAULT_TIMEOUT
-from syndesi.tools.types import NumberLike, is_number
+from ..component import Component
+from ..tools.errors import (
+    AdapterDisconnected,
+    AdapterFailedToOpen,
+    AdapterTimeoutError,
+    BackendCommunicationError,
+)
+from ..tools.types import NumberLike, is_number
 
 from ..tools.backend_api import (
     BACKEND_PORT,
+    DEFAULT_ADAPTER_OPEN_TIMEOUT,
+    EXTRA_BUFFER_RESPONSE_TIME,
     Action,
     BackendResponse,
     Fragment,
     default_host,
     raise_if_error,
-    EXTRA_BUFFER_RESPONSE_TIME
 )
 from ..tools.log_settings import LoggerAlias
 from .backend.adapter_backend import (
-    AdapterDisconnected,
-    AdapterResponseTimeout,
+    AdapterDisconnectedSignal,
     AdapterReadPayload,
+    AdapterResponseTimeout,
     AdapterSignal,
 )
+from .backend.backend_tools import BACKEND_REQUEST_DEFAULT_TIMEOUT
 from .backend.descriptors import Descriptor
-from .stop_condition import StopCondition, Continuation, StopConditionType, Total
+from .stop_condition import Continuation, StopCondition, StopConditionType
 from .timeout import Timeout, TimeoutAction, any_to_timeout
 
 DEFAULT_STOP_CONDITION = Continuation(time=0.1)
 
-DEFAULT_TIMEOUT = Timeout(response=5, action='error')
+DEFAULT_TIMEOUT = Timeout(response=5, action="error")
 
 # Maximum time to let the backend start
 START_TIMEOUT = 2
 # Time to shutdown the backend
 SHUTDOWN_DELAY = 2
 
+
 class SignalQueue(queue.Queue[AdapterSignal]):
+    """
+    A smart queue to hold adapter signals
+    """
     def __init__(self) -> None:
         self._read_payload_counter = 0
         super().__init__(0)
 
     def has_read_payload(self) -> bool:
+        """
+        Return True if the queue contains a read payload
+        """
         return self._read_payload_counter > 0
 
-
-    def put(self, signal: AdapterSignal, block: bool = True, timeout: float | None = None) -> None:
+    def put(self, signal: AdapterSignal) -> None:
+        """
+        Put a signal in the queue
+        
+        Parameters
+        ----------
+        signal : AdapterSignal
+        """
         if isinstance(signal, AdapterReadPayload):
             self._read_payload_counter += 1
-        return super().put(signal, block, timeout)
-    
+        return super().put(signal)
 
     def get(self, block: bool = True, timeout: float | None = None) -> AdapterSignal:
+        """
+        Get an AdapterSignal from the queue
+        """
         signal = super().get(block, timeout)
         if isinstance(signal, AdapterReadPayload):
             self._read_payload_counter -= 1
         return signal
 
-
 def is_backend_running(address: str, port: int) -> bool:
-
+    """
+    Return True if the backend is running
+    """
     try:
         conn = Client((address, port))
     except ConnectionRefusedError:
         return False
-    else:
-        conn.close()
-        return True
+    conn.close()
+    return True
 
 def start_backend(port: int | None = None) -> None:
+    """
+    Start the backend in a separate process
+
+    A custom port can be specified
+
+    Parameters
+    ----------
+    port : int
+    """
     arguments = [
-            sys.executable,
-            "-m",
-            "syndesi.adapters.backend.backend",
-            "-s",
-            str(SHUTDOWN_DELAY),
-            "-q",
-            "-p",
-            str(BACKEND_PORT if port is None else port),
-        ]
-    
-    stdin  = subprocess.DEVNULL
+        sys.executable,
+        "-m",
+        "syndesi.adapters.backend.backend",
+        "-s",
+        str(SHUTDOWN_DELAY),
+        "-q",
+        "-p",
+        str(BACKEND_PORT if port is None else port),
+    ]
+
+    stdin = subprocess.DEVNULL
     stdout = subprocess.DEVNULL
     stderr = subprocess.DEVNULL
 
     if os.name == "posix":
-        subprocess.Popen(
+        subprocess.Popen( #pylint: disable=consider-using-with
             arguments,
             stdin=stdin,
             stdout=stdout,
@@ -122,14 +156,14 @@ def start_backend(port: int | None = None) -> None:
 
     else:
         # Windows: detach from the parent's console so keyboard Ctrl+C won't propagate.
-        CREATE_NEW_PROCESS_GROUP = subprocess.CREATE_NEW_PROCESS_GROUP # type: ignore
-        DETACHED_PROCESS = 0x00000008          # not exposed by subprocess on all Pythons
+        create_new_process_group = subprocess.CREATE_NEW_PROCESS_GROUP  # type: ignore
+        detached_process = 0x00000008  # not exposed by subprocess on all Pythons
         # Optional: CREATE_NO_WINDOW (no window even for console apps)
-        CREATE_NO_WINDOW = 0x08000000
+        create_no_window = 0x08000000
 
-        creationflags = CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS | CREATE_NO_WINDOW
+        creationflags = create_new_process_group | detached_process | create_no_window
 
-        subprocess.Popen(
+        subprocess.Popen( #pylint: disable=consider-using-with
             arguments,
             stdin=stdin,
             stdout=stdout,
@@ -138,13 +172,29 @@ def start_backend(port: int | None = None) -> None:
             close_fds=True,
         )
 
+
 class ReadScope(Enum):
-    NEXT = 'next'
-    BUFFERED = 'buffered'
+    """
+    Read scope
+
+    NEXT : Only read data after the start of the read() call
+    BUFFERED : Return any data that was present before the read() call
+    """
+    NEXT = "next"
+    BUFFERED = "buffered"
+
+
+class Adapter(Component[bytes]):
+    """
+    Adapter class
 
-class Adapter(ABC):
+    An adapter permits communication with a hardware device.
+    The adapter is the user interface of the backend adapter
+    """
+    #pylint: disable=too-many-instance-attributes
     def __init__(
         self,
+        *,
         descriptor: Descriptor,
         alias: str = "",
         stop_conditions: StopCondition | EllipsisType | list[StopCondition] = ...,
@@ -169,9 +219,7 @@ class Adapter(ABC):
         encoding : str
             Which encoding to use if str has to be encoded into bytes
         """
-        self._init_ok = False
-        super().__init__()
-        self._logger = logging.getLogger(LoggerAlias.ADAPTER.value)
+        super().__init__(LoggerAlias.ADAPTER)
         self.encoding = encoding
         self._signal_queue: SignalQueue = SignalQueue()
         self.event_callback: Callable[[AdapterSignal], None] | None = event_callback
@@ -179,17 +227,12 @@ class Adapter(ABC):
         self._backend_connection_lock = threading.Lock()
         self._make_backend_request_queue: queue.Queue[BackendResponse] = queue.Queue()
         self._make_backend_request_flag = threading.Event()
-        self.opened = False
+        self._opened = False
         self._alias = alias
 
-        if backend_address is None:
-            self._backend_address = default_host
-        else:
-            self._backend_address = backend_address
-        if backend_port is None:
-            self._backend_port = BACKEND_PORT
-        else:
-            self._backend_port = backend_port
+        # Use custom backend or the default one
+        self._backend_address = default_host if backend_address is None else backend_address
+        self._backend_port = BACKEND_PORT if backend_port is None else backend_port
 
         # There a two possibilities here
         # A) The descriptor is fully initialized
@@ -197,9 +240,6 @@ class Adapter(ABC):
         # B) The descriptor is not fully initialized
         #    -> Wait for the protocol to set defaults and then connect the adapter
 
-        assert isinstance(
-            descriptor, Descriptor
-        ), "descriptor must be a Descriptor class"
         self.descriptor = descriptor
         self.auto_open = auto_open
 
@@ -215,7 +255,7 @@ class Adapter(ABC):
             elif isinstance(stop_conditions, list):
                 self._stop_conditions = stop_conditions
             else:
-                raise ValueError('Invalid stop_conditions')
+                raise ValueError("Invalid stop_conditions")
 
         # Set the timeout
         self.is_default_timeout = False
@@ -239,7 +279,6 @@ class Adapter(ABC):
             self.connect()
 
         weakref.finalize(self, self._cleanup)
-        self._init_ok = True
 
         # We can auto-open only if auto_open is enabled and if
         # connection with the backend has been made (descriptor initialized)
@@ -247,6 +286,9 @@ class Adapter(ABC):
             self.open()
 
     def connect(self) -> None:
+        """
+        Connect to the backend
+        """
         if self.backend_connection is not None:
             # No need to connect, everything has been done already
             return
@@ -272,7 +314,7 @@ class Adapter(ABC):
         try:
             self.backend_connection = Client((default_host, BACKEND_PORT))
         except ConnectionRefusedError as err:
-            raise RuntimeError("Failed to connect to backend") from err
+            raise BackendCommunicationError("Failed to connect to backend") from err
         self._read_thread = threading.Thread(
             target=self.read_thread,
             args=(self._signal_queue, self._make_backend_request_queue),
@@ -289,7 +331,12 @@ class Adapter(ABC):
         if self.auto_open:
             self.open()
 
-    def _make_backend_request(self, action: Action, *args: Any) -> BackendResponse:
+    def _make_backend_request(
+        self,
+        action: Action,
+        *args: Any,
+        timeout: float = BACKEND_REQUEST_DEFAULT_TIMEOUT,
+    ) -> BackendResponse:
         """
         Send a request to the backend and return the arguments
         """
@@ -300,11 +347,9 @@ class Adapter(ABC):
 
         self._make_backend_request_flag.set()
         try:
-            response = self._make_backend_request_queue.get(
-                timeout=BACKEND_REQUEST_DEFAULT_TIMEOUT
-            )
+            response = self._make_backend_request_queue.get(timeout=timeout)
         except queue.Empty as err:
-            raise RuntimeError(
+            raise BackendCommunicationError(
                 f"Failed to receive response from backend to {action}"
             ) from err
 
@@ -320,24 +365,33 @@ class Adapter(ABC):
         signal_queue: SignalQueue,
         request_queue: queue.Queue[BackendResponse],
     ) -> None:
+        """
+        Main adapter thread, it constantly listens for data coming from the backend
+        
+        - signal -> put only the signal in the signal queue
+        - otherwise -> put the whole request in the request queue
+        """
         while True:
             try:
                 if self.backend_connection is None:
                     raise RuntimeError("Backend connection wasn't initialized")
                 response: tuple[Any, ...] = self.backend_connection.recv()
             except (EOFError, TypeError, OSError):
-                signal_queue.put(AdapterDisconnected())
+                signal_queue.put(AdapterDisconnectedSignal())
                 request_queue.put((Action.ERROR_BACKEND_DISCONNECTED,))
                 break
             else:
                 if not isinstance(response, tuple):
-                    raise RuntimeError(f"Invalid response from backend : {response}")
+                    raise BackendCommunicationError(
+                        f"Invalid response from backend : {response}"
+                    )
                 action = Action(response[0])
 
                 if action == Action.ADAPTER_SIGNAL:
-                #if is_event(action):
                     if len(response) <= 1:
-                        raise RuntimeError(f"Invalid event response : {response}")
+                        raise BackendCommunicationError(
+                            f"Invalid event response : {response}"
+                        )
                     signal: AdapterSignal = response[1]
                     if self.event_callback is not None:
                         self.event_callback(signal)
@@ -361,7 +415,8 @@ class Adapter(ABC):
 
     def set_default_timeout(self, default_timeout: Timeout | None) -> None:
         """
-        Set the default timeout for this adapter. If a previous timeout has been set, it will be fused
+        Set the default timeout for this adapter. If a previous
+        timeout has been set, it will be fused
 
         Parameters
         ----------
@@ -371,7 +426,9 @@ class Adapter(ABC):
             self._logger.debug(f"Setting default timeout to {default_timeout}")
             self._timeout = default_timeout
 
-    def set_stop_conditions(self, stop_conditions: StopCondition | None | list[StopCondition]) -> None:
+    def set_stop_conditions(
+        self, stop_conditions: StopCondition | None | list[StopCondition]
+    ) -> None:
         """
         Overwrite the stop-condition
 
@@ -399,7 +456,7 @@ class Adapter(ABC):
         if self._default_stop_condition:
             self.set_stop_conditions(stop_condition)
 
-    def flushRead(self) -> None:
+    def flush_read(self) -> None:
         """
         Flush the input buffer
         """
@@ -411,7 +468,6 @@ class Adapter(ABC):
                 self._signal_queue.get(block=False)
             except queue.Empty:
                 break
-            
 
     def previous_read_buffer_empty(self) -> bool:
         """
@@ -427,9 +483,20 @@ class Adapter(ABC):
         """
         Start communication with the device
         """
-        self._make_backend_request(Action.OPEN, self._stop_conditions)
+        self._make_backend_request(
+            Action.OPEN,
+            self._stop_conditions,
+            timeout=BACKEND_REQUEST_DEFAULT_TIMEOUT + DEFAULT_ADAPTER_OPEN_TIMEOUT,
+        )
         self._logger.info("Adapter opened")
-        self.opened = True
+        self._opened = True
+
+    def try_open(self) -> bool:
+        try:
+            self.open()
+        except AdapterFailedToOpen:
+            return False
+        return True
 
     def close(self, force: bool = False) -> None:
         """
@@ -445,9 +512,19 @@ class Adapter(ABC):
             if self.backend_connection is not None:
                 self.backend_connection.close()
 
-        self.opened = False
+        self._opened = False
 
-    def write(self, data: bytes | str) -> None:
+    def is_opened(self) -> bool:
+        """
+        Return True if the adapter is opened and False otherwise
+
+        Returns
+        -------
+        opened : bool
+        """
+        return self._opened
+
+    def write(self, data: bytes) -> None:
         """
         Send data to the device
 
@@ -464,7 +541,7 @@ class Adapter(ABC):
         self,
         timeout: Timeout | EllipsisType | None = ...,
         stop_conditions: StopCondition | EllipsisType | list[StopCondition] = ...,
-        scope : str = ReadScope.BUFFERED.value,
+        scope: str = ReadScope.BUFFERED.value,
     ) -> AdapterReadPayload:
         """
         Read data from the device
@@ -490,13 +567,13 @@ class Adapter(ABC):
             read_timeout = self._timeout
         else:
             read_timeout = any_to_timeout(timeout)
-            
+
         if read_timeout is None:
             raise RuntimeError("Cannot read without setting a timeout")
 
         if stop_conditions is not ...:
             if isinstance(stop_conditions, StopCondition):
-                stop_conditions = [stop_conditions]    
+                stop_conditions = [stop_conditions]
             self._make_backend_request(Action.SET_STOP_CONDITIONs, stop_conditions)
 
         # First, we check if data is in the buffer and if the scope if set to BUFFERED
@@ -525,52 +602,54 @@ class Adapter(ABC):
                 # Wait for the response time + a bit more
                 read_stop_timestamp = read_init_time + _response
 
-            # else:
-            #     start_read_id = None
-            #     read_init_time = None
-
-            
             while True:
                 try:
                     if read_stop_timestamp is None:
                         queue_timeout = None
                     else:
-                        queue_timeout = max(0, read_stop_timestamp - time.time() + EXTRA_BUFFER_RESPONSE_TIME)
+                        queue_timeout = max(
+                            0,
+                            read_stop_timestamp
+                            - time.time()
+                            + EXTRA_BUFFER_RESPONSE_TIME,
+                        )
 
                     signal = self._signal_queue.get(timeout=queue_timeout)
-                except queue.Empty:
-                    raise RuntimeError('Failed to receive response from backend')
+                except queue.Empty as e:
+                    raise BackendCommunicationError(
+                        "Failed to receive response from backend"
+                    ) from e
                 if isinstance(signal, AdapterReadPayload):
                     output_signal = signal
                     break
-                elif isinstance(signal, AdapterDisconnected):
-                    raise RuntimeError("Adapter disconnected")
-                elif isinstance(signal, AdapterResponseTimeout):
+                if isinstance(signal, AdapterDisconnectedSignal):
+                    raise AdapterDisconnected()
+                if isinstance(signal, AdapterResponseTimeout):
                     if start_read_id == signal.identifier:
                         output_signal = None
                         break
                     # Otherwise ignore it
 
         if output_signal is None:
-            # TODO : Make read_timeout always Timeout, never None ?
             match read_timeout.action:
                 case TimeoutAction.RETURN_EMPTY:
                     t = time.time()
                     return AdapterReadPayload(
-                        fragments=[Fragment(b'', t)],
+                        fragments=[Fragment(b"", t)],
                         stop_timestamp=t,
                         stop_condition_type=StopConditionType.TIMEOUT,
                         previous_read_buffer_used=False,
                         response_timestamp=None,
-                        response_delay=None
+                        response_delay=None,
                     )
                 case TimeoutAction.ERROR:
-                    raise TimeoutError(
-                        f"No response received from device within {read_timeout.response()} seconds"
+                    timeout_value = read_timeout.response()
+                    raise AdapterTimeoutError(
+                        float("nan") if timeout_value is None else timeout_value
                     )
                 case _:
                     raise NotImplementedError()
-        
+
         else:
             return output_signal
 
@@ -583,7 +662,7 @@ class Adapter(ABC):
         return signal.data()
 
     def _cleanup(self) -> None:
-        if self._init_ok and self.opened:
+        if self._opened:
             self.close()
 
     def query_detailed(
@@ -598,7 +677,7 @@ class Adapter(ABC):
         - write
         - read
         """
-        self.flushRead()
+        self.flush_read()
         self.write(data)
         return self.read_detailed(timeout=timeout, stop_conditions=stop_conditions)
 

syndesi/adapters/auto.py

@@ -1,17 +1,19 @@
 # File : auto.py
 # Author : Sébastien Deriaz
 # License : GPL
-#
-# Automatic adapter function
-# This function is used to automatically choose an adapter based on the user's input
-# 192.168.1.1 -> IP
-# COM4 -> Serial
-# /dev/tty* -> Serial
-# etc...
-# If an adapter class is supplied, it is passed through
-#
-# Additionnaly, it is possible to do COM4:115200 so as to make the life of the user easier
-# Same with /dev/ttyACM0:115200
+
+"""
+Automatic adapter function
+This function is used to automatically choose an adapter based on the user's input
+192.168.1.1 -> IP
+COM4 -> Serial
+/dev/tty* -> Serial
+etc...
+If an adapter class is supplied, it is passed through
+
+Additionnaly, it is possible to do COM4:115200 so as to make the life of the user easier
+Same with /dev/ttyACM0:115200
+"""
 
 
 from .adapter import Adapter
@@ -27,6 +29,15 @@ from .visa import Visa
 
 
 def auto_adapter(adapter_or_string: Adapter | str) -> Adapter:
+    """
+    Create an adapter from a string or an adapter
+
+    - <int>.<int>.<int>.<int>[:<int>] -> IP
+    - x.y[:<int>] -> IP
+    - COM<int> -> SerialPort
+    - /dev/tty[ACM|USB]<int> -> SerialPort
+
+    """
     if isinstance(adapter_or_string, Adapter):
         # Simply return it
         return adapter_or_string
@@ -39,12 +50,12 @@ def auto_adapter(adapter_or_string: Adapter | str) -> Adapter:
                 port=descriptor.port,
                 transport=descriptor.transport.value,
             )
-        elif isinstance(descriptor, SerialPortDescriptor):
+        if isinstance(descriptor, SerialPortDescriptor):
             return SerialPort(port=descriptor.port, baudrate=descriptor.baudrate)
-        elif isinstance(descriptor, VisaDescriptor):
+        if isinstance(descriptor, VisaDescriptor):
             return Visa(descriptor=descriptor.descriptor)
-        else:
-            raise RuntimeError(f"Invalid descriptor : {descriptor}")
+
+        raise RuntimeError(f"Invalid descriptor : {descriptor}")
 
     else:
         raise ValueError(f"Invalid adapter : {adapter_or_string}")