syndesi 0.4.2__tar.gz → 0.4.4__tar.gz

{syndesi-0.4.2/syndesi.egg-info → syndesi-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: syndesi
-Version: 0.4.2
+Version: 0.4.4
 Summary: Syndesi
 Author-email: Sébastien Deriaz <sebastien.deriaz1@gmail.com>
 License: GPL

{syndesi-0.4.2 → syndesi-0.4.4}/pyproject.toml

@@ -69,3 +69,9 @@ exclude = ["^tests/fixtures/"]
 skips = ["B101"]
 exclude = ["tests"]
 
+[tool.pylint]
+# Disable too-many-arguments, this is the case for adapters/protocols/drivers
+# All arguments are necessary and it would not make sense to group them / move them
+# too-many-positional-arguments is kept however because it makes sense
+# Also disable W1203 to allow f-strings in logging lines
+disable = ["R0913", "W1203"]

{syndesi-0.4.2 → syndesi-0.4.4}/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-0.4.2 → syndesi-0.4.4}/syndesi/adapters/adapter.py

@@ -1,19 +1,21 @@
 # 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
+
+"""
+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
@@ -30,10 +32,18 @@ from multiprocessing.connection import Client, Connection
 from types import EllipsisType
 from typing import Any
 
-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,
@@ -43,7 +53,7 @@ from ..tools.backend_api import (
 )
 from ..tools.log_settings import LoggerAlias
 from .backend.adapter_backend import (
-    AdapterDisconnected,
+    AdapterDisconnectedSignal,
     AdapterReadPayload,
     AdapterResponseTimeout,
     AdapterSignal,
@@ -64,39 +74,61 @@ 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",
@@ -113,7 +145,7 @@ def start_backend(port: int | None = None) -> None:
     stderr = subprocess.DEVNULL
 
     if os.name == "posix":
-        subprocess.Popen(
+        subprocess.Popen( #pylint: disable=consider-using-with
             arguments,
             stdin=stdin,
             stdout=stdout,
@@ -124,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,
@@ -142,13 +174,27 @@ def start_backend(port: int | None = None) -> None:
 
 
 class ReadScope(Enum):
+    """
+    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(ABC):
+class Adapter(Component[bytes]):
+    """
+    Adapter class
+
+    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] = ...,
@@ -173,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
@@ -183,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
@@ -201,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
 
@@ -243,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)
@@ -251,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
@@ -276,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),
@@ -293,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
         """
@@ -304,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
 
@@ -324,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)
@@ -365,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
         ----------
@@ -405,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
         """
@@ -432,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:
         """
@@ -450,9 +512,19 @@ class Adapter(ABC):
             if self.backend_connection is not None:
                 self.backend_connection.close()
 
-        self.opened = False
+        self._opened = False
+
+    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 | str) -> None:
+    def write(self, data: bytes) -> None:
         """
         Send data to the device
 
@@ -544,13 +616,15 @@ class Adapter(ABC):
 
                     signal = self._signal_queue.get(timeout=queue_timeout)
                 except queue.Empty as e:
-                    raise RuntimeError("Failed to receive response from backend") from 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
@@ -569,8 +643,9 @@ class Adapter(ABC):
                         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()
@@ -587,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(
@@ -602,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-0.4.2 → syndesi-0.4.4}/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}")

{syndesi-0.4.2 → syndesi-0.4.4}/syndesi/adapters/backend/adapter_backend.py

@@ -61,7 +61,7 @@ class AdapterSignal:
     pass
 
 
-class AdapterDisconnected(AdapterSignal):
+class AdapterDisconnectedSignal(AdapterSignal):
     def __str__(self) -> str:
         return "Adapter disconnected"
 
@@ -211,7 +211,7 @@ class AdapterBackend(ABC):
         return self._previous_buffer.data == b""
 
     @abstractmethod
-    def open(self) -> bool:
+    def open(self) -> None:
         """
         Start communication with the device
         """
@@ -261,7 +261,7 @@ class AdapterBackend(ABC):
             fragment_delta_t = float("nan")
         if fragment.data == b"":
             self.close()
-            yield AdapterDisconnected()
+            yield AdapterDisconnectedSignal()
         else:
             self._logger.debug(
                 f"New fragment {fragment_delta_t:+.3f} {fragment}"

{syndesi-0.4.2 → syndesi-0.4.4}/syndesi/adapters/backend/adapter_session.py

@@ -16,7 +16,7 @@ from typing import Any
 from syndesi.adapters.backend.stop_condition_backend import (
     stop_condition_to_backend,
 )
-from syndesi.tools.errors import make_error_description
+from syndesi.tools.errors import AdapterError, make_error_description
 from syndesi.tools.types import NumberLike
 
 from ...tools.backend_api import Action, frontend_send
@@ -99,16 +99,12 @@ class AdapterSession(threading.Thread):
             self._shutdown_counter_top = None
             self._shutdown_counter = None
 
-        # self._timeout_events: list[tuple[TimeoutEvent, float]] = []
-
         self._read_init_id = 0
 
     def add_connection(self, conn: NamedConnection) -> None:
         with self._connections_lock:
             self.connections.append(conn)
-            # os.write(self._new_connection_w, b"\x00")
             self._new_connection_w.send(b"\x00")
-            self._logger.info(f"New client : {conn.remote()}")
 
     def _remove_connection(self, conn: NamedConnection) -> None:
         with self._connections_lock:
@@ -272,12 +268,15 @@ class AdapterSession(threading.Thread):
                             self._adapter.set_stop_conditions(
                                 [stop_condition_to_backend(sc) for sc in request[1]]
                             )
-                            if self._adapter.open():
+                            try:
+                                self._adapter.open()
+                            except AdapterError as e:
                                 # Success !
-                                response_action = Action.OPEN
-                            else:
                                 response_action = Action.ERROR_FAILED_TO_OPEN
-                            extra_arguments = ("",)
+                                extra_arguments = (str(e),)
+                            else:
+                                response_action = Action.OPEN
+                                extra_arguments = ("",)
                         case Action.WRITE:
                             data = request[1]
                             if self._adapter.is_opened():

{syndesi-0.4.2 → syndesi-0.4.4}/syndesi/adapters/backend/backend.py

@@ -98,6 +98,8 @@ def is_request(x: object) -> TypeGuard[tuple[str, object]]:
 
 class Backend:
     MONITORING_DELAY = 0.5
+    NEW_CLIENT_REQUEST_TIMEOUT = 0.5
+
     _session_shutdown_delay: NumberLike | None
     _backend_shutdown_delay: NumberLike | None
     _backend_shutdown_timestamp: NumberLike | None
@@ -278,7 +280,9 @@ class Backend:
         # Wait for adapter
         # ready = wait([client.conn], timeout=0.1)
         # selectors to work on Unix and Windows
-        ready, _, _ = select.select([client.conn], [], [], 0.1)
+        ready, _, _ = select.select(
+            [client.conn], [], [], self.NEW_CLIENT_REQUEST_TIMEOUT
+        )
         if len(ready) == 0:
             client.conn.close()
             return
@@ -290,6 +294,7 @@ class Backend:
         action = Action(adapter_request[0])
         if action == Action.SELECT_ADAPTER:
             adapter_descriptor = adapter_request[1]
+            self._logger.info(f"New client for {adapter_descriptor}")
             # If the session exists but it is dead, delete it
             if (
                 adapter_descriptor in self.adapter_sessions
@@ -299,7 +304,7 @@ class Backend:
 
             if adapter_descriptor not in self.adapter_sessions:
                 # Create the adapter backend thread
-                self._logger.info(f"Creating adapter session for {adapter_descriptor}")
+                # self._logger.info(f"Creating adapter session for {adapter_descriptor}")
                 thread = AdapterSession(
                     adapter_descriptor, shutdown_delay=self._session_shutdown_delay
                 )  # TODO : Put another delay here ?