syndesi 0.4.2__py3-none-any.whl → 0.5.0__py3-none-any.whl

syndesi/cli/terminal_tools.py

@@ -3,12 +3,12 @@
 # License : GPL
 
 
-class TerminalCompatible:
-    name = "..."
-    description = "..."
-    help = "..."
-    aliases = "..."
-    # prompt settings ? color ?
+# class TerminalCompatible:
+#     name = "..."
+#     description = "..."
+#     help = "..."
+#     aliases = "..."
+#     # prompt settings ? color ?
 
-    def handle_input(self, user_input: str | bytes) -> None:
-        pass
+#     def handle_input(self, user_input: str | bytes) -> None:
+#         pass

syndesi/component.py

@@ -0,0 +1,315 @@
+# File : component.py
+# Author : Sébastien Deriaz
+# License : GPL
+"""
+Component is the base of the main syndesi classes : Adapters, Protocols and Drivers
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from concurrent.futures import Future
+from dataclasses import dataclass, field
+from enum import StrEnum
+from types import EllipsisType
+from typing import Generic, TypeVar
+
+from syndesi.adapters.stop_conditions import Fragment, StopCondition, StopConditionType
+from syndesi.adapters.timeout import Timeout
+from syndesi.tools.errors import AdapterOpenError, WorkerThreadError
+
+from .tools.log_settings import LoggerAlias
+
+
+class Event:
+    """Generic event, used to move information asynchronously from the adapter worker thread"""
+
+
+class Descriptor(ABC):
+    """
+    Descriptor base class. A descriptor is a string to define the main parameters
+    of an adapter (ip address, port, baudrate, etc...)
+    """
+
+    DETECTION_PATTERN = ""
+
+    def __init__(self) -> None:
+        return None
+
+    @staticmethod
+    @abstractmethod
+    def from_string(string: str) -> "Descriptor":
+        """
+        Create a Descriptor class from a string
+        """
+
+    @abstractmethod
+    def is_initialized(self) -> bool:
+        """Return True if the descriptor is initialized"""
+
+
+T = TypeVar("T")
+
+
+@dataclass
+class Frame(Generic[T]):
+    """
+    Adapter signal containing received data
+    """
+
+    stop_timestamp: float | None
+    stop_condition_type: StopConditionType | None  # None if it's a response timeout
+    previous_read_buffer_used: bool
+    response_delay: float | None
+
+    @abstractmethod
+    def get_payload(self) -> T:
+        """
+        Return frame payload
+        """
+
+    @abstractmethod
+    def __str__(self) -> str: ...
+
+
+@dataclass
+class AdapterFrame(Frame[bytes]):
+    """
+    Adapter frame
+    """
+
+    fragments: list[Fragment] = field(default_factory=lambda: [])
+
+    def get_payload(self) -> bytes:
+        """
+        Return all fragement data as a combined bytes array
+        """
+        return b"".join([f.data for f in self.fragments])
+
+    def __str__(self) -> str:
+        return f"AdapterFrame({self.get_payload()!r})"
+
+
+R = TypeVar("R")
+
+
+class ThreadCommand(Future[R]):
+    """
+    Command object completed by the worker thread.
+
+    - .future is a concurrent.futures.Future => compatible with asyncio.wrap_future
+    - .result() raises WorkerThreadError on command-timeout (worker not responding),
+      not on device read timeouts (those are handled in the worker and surfaced as Adapter* errors).
+    """
+
+    def result(self, timeout: float | None = None) -> R:
+        """
+        Return the result of the thread command
+        """
+        try:
+            return super().result(timeout=timeout)
+        except TimeoutError:
+            raise WorkerThreadError(
+                f"No response from worker thread to {type(self).__name__} within {timeout}s"
+            ) from None
+
+
+class ReadScope(StrEnum):
+    """
+    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 Component(ABC, Generic[T]):
+    """Syndesi Component
+
+    A Component is the elementary class of Syndesi. It is the base
+    of all classes the user will be using
+    """
+
+    def __init__(self, logger_alias: LoggerAlias) -> None:
+        super().__init__()
+        self._logger = logging.getLogger(logger_alias.value)
+
+    # ==== open ====
+
+    @abstractmethod
+    def open(self) -> None:
+        """Open the component"""
+
+    @abstractmethod
+    async def aopen(self) -> None:
+        """Asynchronously open the component"""
+
+    # ==== try_open ====
+
+    async def atry_open(self) -> bool:
+        """
+        Async try to open communication with the device
+        Return True if sucessful and False otherwise
+
+        Returns
+        -------
+        success : bool
+        """
+        try:
+            await self.aopen()
+            return True
+        except AdapterOpenError:
+            return False
+
+    def try_open(self) -> bool:
+        """
+        Try to open communication with the device
+        Return True if sucessful and False otherwise
+
+        Returns
+        -------
+        success : bool
+        """
+        try:
+            self.open()
+        except AdapterOpenError:
+            return False
+        return True
+
+    # ==== close ====
+
+    @abstractmethod
+    def close(self) -> None:
+        """Close the component"""
+
+    @abstractmethod
+    async def aclose(self) -> None:
+        """Asynchronously close the component"""
+
+    # ==== read_detailed ====
+
+    @abstractmethod
+    async def aread_detailed(
+        self,
+        timeout: Timeout | EllipsisType | None = ...,
+        stop_conditions: StopCondition | EllipsisType | list[StopCondition] = ...,
+        scope: str = ReadScope.BUFFERED.value,
+    ) -> Frame[T]:
+        """Asynchronously read data from the component and return a Frame object"""
+
+    @abstractmethod
+    def read_detailed(
+        self,
+        timeout: Timeout | EllipsisType | None = ...,
+        stop_conditions: StopCondition | EllipsisType | list[StopCondition] = ...,
+        scope: str = ReadScope.BUFFERED.value,
+    ) -> Frame[T]:
+        """Read data from the component and return a Frame object"""
+
+    # ==== read ====
+
+    @abstractmethod
+    async def aread(
+        self,
+        timeout: Timeout | EllipsisType | None = ...,
+        stop_conditions: StopCondition | EllipsisType | list[StopCondition] = ...,
+        scope: str = ReadScope.BUFFERED.value,
+    ) -> T:
+        """Asynchronously read data from the component"""
+
+    @abstractmethod
+    def read(
+        self,
+        timeout: Timeout | EllipsisType | None = ...,
+        stop_conditions: StopCondition | EllipsisType | list[StopCondition] = ...,
+        scope: str = ReadScope.BUFFERED.value,
+    ) -> T:
+        """Read data from the component"""
+
+    # ==== flush_read ====
+
+    @abstractmethod
+    async def aflush_read(self) -> None:
+        """Clear input buffer"""
+
+    @abstractmethod
+    def flush_read(self) -> None:
+        """Clear input buffer"""
+
+    # ==== write ====
+
+    @abstractmethod
+    async def awrite(self, data: T) -> None:
+        """Asynchronously write data to the component"""
+
+    @abstractmethod
+    def write(self, data: T) -> None:
+        """Synchronously write data to the component"""
+
+    # ==== query_detailed ====
+
+    @abstractmethod
+    async def aquery_detailed(
+        self,
+        payload: T,
+        timeout: Timeout | None | EllipsisType = ...,
+        stop_conditions: StopCondition | EllipsisType | list[StopCondition] = ...,
+        scope: str = ReadScope.BUFFERED.value,
+    ) -> Frame[T]:
+        """
+        Asynchronously query the component and return a Frame object
+        """
+
+    @abstractmethod
+    def query_detailed(
+        self,
+        payload: T,
+        timeout: Timeout | None | EllipsisType = ...,
+        stop_conditions: StopCondition | EllipsisType | list[StopCondition] = ...,
+        scope: str = ReadScope.BUFFERED.value,
+    ) -> Frame[T]:
+        """
+        Synchronously query the component and return a Frame object
+        """
+
+    # ==== query ====
+
+    async def aquery(
+        self,
+        payload: T,
+        timeout: Timeout | None | EllipsisType = ...,
+        stop_conditions: StopCondition | EllipsisType | list[StopCondition] = ...,
+        scope: str = ReadScope.BUFFERED.value,
+    ) -> T:
+        """Asynchronously query the component"""
+        output_frame = await self.aquery_detailed(
+            payload=payload,
+            timeout=timeout,
+            stop_conditions=stop_conditions,
+            scope=scope,
+        )
+        return output_frame.get_payload()
+
+    def query(
+        self,
+        payload: T,
+        timeout: Timeout | None | EllipsisType = ...,
+        stop_conditions: StopCondition | EllipsisType | list[StopCondition] = ...,
+        scope: str = ReadScope.BUFFERED.value,
+    ) -> T:
+        """Query the component"""
+        output_frame = self.query_detailed(
+            payload=payload,
+            timeout=timeout,
+            stop_conditions=stop_conditions,
+            scope=scope,
+        )
+        return output_frame.get_payload()
+
+    # ==== Other ====
+
+    @abstractmethod
+    def is_open(self) -> bool:
+        """Return True if the component is open"""

syndesi/protocols/delimited.py

@@ -1,48 +1,75 @@
 # File : delimited.py
 # Author : Sébastien Deriaz
 # License : GPL
+"""
+Delimited protocol, formats data when communicating with devices expecting
+command-like formats with specified delimiters (like \\n, \\r, \\r\\n, etc...)
+"""
 
 from collections.abc import Callable
 from types import EllipsisType
 
+from syndesi.adapters.adapter_worker import (
+    AdapterDisconnectedEvent,
+    AdapterEvent,
+    AdapterFrameEvent,
+)
+
 from ..adapters.adapter import Adapter
-from ..adapters.backend.adapter_backend import AdapterReadPayload, AdapterSignal
-from ..adapters.stop_condition import StopCondition, Termination
+from ..adapters.stop_conditions import StopCondition, Termination
 from ..adapters.timeout import Timeout
-from .protocol import Protocol
+from ..component import AdapterFrame, ReadScope
+from .protocol import (
+    Protocol,
+    ProtocolDisconnectedEvent,
+    ProtocolEvent,
+    ProtocolFrame,
+    ProtocolFrameEvent,
+)
+
+
+class DelimitedFrame(ProtocolFrame[str]):
+    """Delimited frame"""
 
+    payload: str
+
+    def __str__(self) -> str:
+        return f"DelimitedFrame({self.payload})"
+
+
+class Delimited(Protocol[str]):
+    """
+    Protocol with delimiter, like LF, CR, etc... LF is used by default
+
+    No presentation or application layers
+
+    Parameters
+    ----------
+    adapter : Adapter
+    termination : bytes
+        Command termination, '\\n' by default
+    format_response : bool
+        Apply formatting to the response (i.e removing the termination), True by default
+    encoding : str or None
+        If None, delimited will not encode/decode
+    timeout : Timeout
+        None by default (default timeout)
+    receive_termination : bytes
+        Termination when receiving only, optional
+        if not set, the value of termination is used
+    """
 
-class Delimited(Protocol):
     def __init__(
         self,
         adapter: Adapter,
         termination: str = "\n",
+        *,
         format_response: bool = True,
         encoding: str = "utf-8",
         timeout: Timeout | None | EllipsisType = ...,
-        event_callback: Callable[[AdapterSignal], None] | None = None,
+        event_callback: Callable[[ProtocolEvent], None] | None = None,
         receive_termination: str | None = None,
     ) -> None:
-        """
-        Protocol with delimiter, like LF, CR, etc... LF is used by default
-
-        No presentation or application layers
-
-        Parameters
-        ----------
-        adapter : Adapter
-        termination : bytes
-            Command termination, '\\n' by default
-        format_response : bool
-            Apply formatting to the response (i.e removing the termination), True by default
-        encoding : str or None
-            If None, delimited will not encode/decode
-        timeout : Timeout
-            None by default (default timeout)
-        receive_termination : bytes
-            Termination when receiving only, optional
-            if not set, the value of termination is used
-        """
         if not isinstance(termination, str) or isinstance(termination, bytes):
             raise ValueError(
                 f"end argument must be of type str or bytes, not {type(termination)}"
@@ -60,76 +87,52 @@ class Delimited(Protocol):
         )
         super().__init__(adapter, timeout=timeout, event_callback=event_callback)
 
-        # Connect the adapter if it wasn't done already
-        self._adapter.connect()
+        self._adapter.set_event_callback(self._on_event)
 
         # TODO : Disable encoding/decoding when encoding==None
 
     def __str__(self) -> str:
         if self._receive_termination == self._termination:
             return f"Delimited({self._adapter},{repr(self._termination)})"
-        else:
-            return f"Delimited({self._adapter},{repr(self._termination)}/{repr(self._receive_termination)})"
-
-    def _default_timeout(self) -> Timeout | None:
-        return Timeout(response=2, action="error")
+        return (
+            f"Delimited({self._adapter},{repr(self._termination)}"
+            "/{repr(self._receive_termination)})"
+        )
 
     def __repr__(self) -> str:
         return self.__str__()
 
-    def _to_bytes(self, command: str | bytes) -> bytes:
-        if isinstance(command, str):
-            return command.encode("ASCII")
-        elif isinstance(command, bytes):
-            return command
-        else:
-            raise ValueError(f"Invalid command type : {type(command)}")
-
-    def _from_bytes(self, payload: bytes) -> str:
-        assert isinstance(payload, bytes)
-        return payload.decode("ASCII")  # TODO : encoding ?
-
-    def _format_command(self, command: str) -> str:
-        return command + self._termination
+    def _default_timeout(self) -> Timeout | None:
+        return Timeout(response=2, action="error")
 
-    def _format_response(self, response: str) -> str:
-        if response.endswith(self._receive_termination):
-            response = response[: -len(self._receive_termination)]
-        return response
+    # ┌────────────┐
+    # │ Public API │
+    # └────────────┘
 
-    def _on_data_ready_event(self, data: AdapterReadPayload) -> None:
-        # TODO : Call the callback here ?
-        # output = self._format_read(data.data(), decode=True)
-        # return output
-        pass
+    # ==== read_detailed ====
 
-    def write(self, command: str) -> None:
-        command = self._format_command(command)
-        self._adapter.write(self._to_bytes(command))
+    def _adapter_to_protocol(self, adapter_frame: AdapterFrame) -> DelimitedFrame:
+        data = adapter_frame.get_payload().decode(self._encoding)
+        if data.endswith(self._receive_termination):
+            data = data[: -len(self._receive_termination)]
 
-    def query(self, data: str, timeout: Timeout | None | EllipsisType = ...) -> str:
-        """
-        Writes then reads from the device and return the result
+        return DelimitedFrame(
+            payload=data,
+            stop_timestamp=adapter_frame.stop_timestamp,
+            stop_condition_type=adapter_frame.stop_condition_type,
+            previous_read_buffer_used=adapter_frame.previous_read_buffer_used,
+            response_delay=adapter_frame.response_delay,
+        )
 
-        Parameters
-        ----------
-        data : str
-            Data to send to the device
-        timeout : Timeout
-            Custom timeout for this query (optional)
-        decode : bool
-            Decode incoming data, True by default
-        full_output : bool
-            return metrics on read operation (False by default)
-        """
-        self._adapter.flushRead()
-        self.write(data)
-        return self.read(timeout=timeout)
+    def _protocol_to_adapter(self, protocol_payload: str) -> bytes:
+        terminated_payload = protocol_payload + self._termination
+        return terminated_payload.encode(self._encoding)
 
     def read_raw(
         self,
         timeout: Timeout | None | EllipsisType = ...,
         stop_conditions: StopCondition | EllipsisType | list[StopCondition] = ...,
+        scope: str = ReadScope.BUFFERED.value,
     ) -> bytes:
         """
         Reads command and formats it as a str
@@ -145,39 +148,21 @@ class Delimited(Protocol):
         """
 
         # Send up to the termination
-        signal = self._adapter.read_detailed(
-            timeout=timeout, stop_conditions=stop_conditions
+        frame = self._adapter.read_detailed(
+            timeout=timeout, stop_conditions=stop_conditions, scope=scope
         )
-        return signal.data()
+        return frame.get_payload()
 
-    def read_detailed(
-        self,
-        timeout: Timeout | None | EllipsisType = ...,
-        stop_conditions: StopCondition | EllipsisType | list[StopCondition] = ...,
-    ) -> AdapterReadPayload:
-        signal = self._adapter.read_detailed(
-            timeout=timeout, stop_conditions=stop_conditions
-        )
-        return signal
+    def _on_event(self, event: AdapterEvent) -> None:
 
-    def read(
-        self,
-        timeout: Timeout | None | EllipsisType = ...,
-        stop_conditions: StopCondition | EllipsisType | list[StopCondition] = ...,
-    ) -> str:
-        signal = self.read_detailed(timeout=timeout, stop_conditions=stop_conditions)
-        return self._decode(signal.data())
-
-    def _decode(self, data: bytes) -> str:
-        try:
-            data_string = data.decode(self._encoding)
-        except UnicodeDecodeError as err:
-            raise ValueError(
-                f"Failed to decode {data!r} to {self._encoding} ({err})"
-            ) from err
-        else:
-            if not self._response_formatting:
-                # Add the termination back in since it was removed by the adapter
-                data_string += self._receive_termination
+        if self._event_callback is not None:
+            output_event: ProtocolEvent | None = None
+            if isinstance(event, AdapterDisconnectedEvent):
+                output_event = ProtocolDisconnectedEvent()
+            if isinstance(event, AdapterFrameEvent):
+                output_event = ProtocolFrameEvent(
+                    frame=self._adapter_to_protocol(event.frame)
+                )
 
-        return data_string
+            if output_event is not None:
+                self._event_callback(output_event)