Merge pull request #10 from MrClock8163/connection-refactor

MrClock8163 · web-flow · commit 06d1f0777654 · 2025-04-24T15:00:40.000+02:00
Connection refactor
diff --git a/src/geocompy/communication.py b/src/geocompy/communication.py
@@ -14,9 +14,13 @@
 from __future__ import annotations
 
 from types import TracebackType
-from typing import Iterable
 
-from serial import Serial, SerialException, SerialTimeoutException
+from serial import (
+    Serial,
+    SerialException,
+    SerialTimeoutException,
+    PARITY_NONE
+)
 
 
 class Connection:
@@ -27,16 +31,6 @@ class Connection:
 
     """
 
-    def __init__(self, name: str = ""):
-        """
-        Parameters
-        ----------
-        name : str, optional
-            Descriptive name, by default ""
-
-        """
-        self.name: str = name
-
     def is_open(self) -> bool:
         """
         Checks if the communication channel is currently open.
@@ -88,32 +82,9 @@ def receive(self) -> str:
         """
         raise NotImplementedError("interface does not implement 'receive'")
 
-    def exchange(self, cmds: Iterable[str]) -> list[str]:
+    def exchange(self, cmd: str) -> str:
         """
-        Sends an arbitrary number of messages through the connection,
-        and receives the corresponding responses.
-
-        Parameters
-        ----------
-        cmds : Iterable[str]
-            Collection of messages to send.
-
-        Returns
-        -------
-        list
-            Responses to the sent messages.
-
-        Raises
-        ------
-        NotImplementedError
-            If the method is not implemented on the child class.
-
-        """
-        raise NotImplementedError("interface does not implement 'exchange'")
-
-    def exchange1(self, cmd: str) -> str:
-        """
-        Sends a single message through the connection, and receives the
+        Sends a message through the connection, and receives the
         corresponding response.
 
         Parameters
@@ -135,6 +106,64 @@ def exchange1(self, cmd: str) -> str:
         raise NotImplementedError("interface does not implement 'exchange1'")
 
 
+def open_serial(
+    port: str,
+    *,
+    speed: int = 9600,
+    databits: int = 8,
+    stopbits: int = 1,
+    parity: str = PARITY_NONE,
+    timeout: int = 15,
+    eom: str = "\r\n",
+    eoa: str = "\r\n"
+) -> SerialConnection:
+    """
+    Constructs a SerialConnection with the given communication
+    parameters.
+
+    Parameters
+    ----------
+    port : str
+        Name of the port to use (e.g. ``COM1`` or ``/dev/ttyUSB0``).
+    speed : int, optional
+        Communication speed (baud), by default 9600
+    databits : int, optional
+        Number of data bits, by default 8
+    stopbits : int, optional
+        Number of stop bits, by default 1
+    parity : str, optional
+        Parity bit behavior, by default PARITY_NONE
+    timeout : int, optional
+        Communication timeout threshold, by default 15
+    eom : str, optional
+        EndOfMessage sequence, by default ``"\\r\\n"``
+    eoa : str, optional
+        EndOfAnswer sequence, by default ``"\\r\\n"``
+
+    Returns
+    -------
+    SerialConnection
+
+    Examples
+    --------
+
+    Opening a serial connection similar to a file:
+
+    >>> conn = open_serial("COM1", speed=19200, timeout=5)
+    >>> # do operations
+    >>> conn.close()
+
+    Using as a context manager:
+
+    >>> with open_serial("COM1", timeout=20) as conn:
+    ...     conn.send("test")
+
+    """
+    serialport = Serial(port, speed, databits, parity, stopbits, timeout)
+    wrapper = SerialConnection(serialport, eom=eom, eoa=eoa)
+    return wrapper
+
+
 class SerialConnection(Connection):
     """
     Connection wrapping an open serial port.
@@ -194,7 +223,6 @@ def __init__(
         be opened.
 
         """
-        super().__init__("")
 
         self._port: Serial = port
         self.eom: str = eom  # end of message
@@ -293,40 +321,9 @@ def receive(self) -> str:
 
         return answer.decode("ascii").removesuffix(self.eoa)
 
-    def exchange(self, cmds: Iterable[str]) -> list[str]:
-        """
-        Writes an arbitrary number of messages to the serial line,
-        and receives the corresponding responses, one pair at a time.
-
-        Parameters
-        ----------
-        cmds : Iterable[str]
-            Collection of messages to send.
-
-        Returns
-        -------
-        list
-            Responses to the sent messages.
-
-        Raises
-        ------
-        ~serial.SerialException
-            If the serial port is not open.
-        ~serial.SerialTimeoutException
-            If the connection timed out before receiving the
-            EndOfAnswer sequence for one of the responses.
-
-        """
-        answers: list[str] = []
-        for item in cmds:
-            self.send(item)
-            answers.append(self.receive())
-
-        return answers
-
-    def exchange1(self, cmd: str) -> str:
+    def exchange(self, cmd: str) -> str:
         """
-        Writes a single message to the serial line, and receives the
+        Writes a message to the serial line, and receives the
         corresponding response.
 
         Parameters
diff --git a/src/geocompy/dna/__init__.py b/src/geocompy/dna/__init__.py
@@ -140,7 +140,7 @@ def __init__(
 
         for i in range(retry):
             try:
-                reply = self._conn.exchange1("a")
+                reply = self._conn.exchange("a")
                 if reply == "?":
                     break
             except Exception:
@@ -178,7 +178,7 @@ def setrequest(
         cmd = f"SET/{param:d}/{value:d}"
         comment = ""
         try:
-            answer = self._conn.exchange1(cmd)
+            answer = self._conn.exchange(cmd)
         except Exception:
             self._logger.error(format_exc())
             answer = DNAErrors.E_UNKNOWN.value
@@ -219,7 +219,7 @@ def confrequest(
         cmd = f"CONF/{param:d}"
         comment = ""
         try:
-            answer = self._conn.exchange1(cmd)
+            answer = self._conn.exchange(cmd)
         except Exception:
             self._logger.error(format_exc())
             answer = DNAErrors.E_UNKNOWN.value
@@ -269,7 +269,7 @@ def putrequest(
         cmd = f"PUT/{word:s}"
         comment = ""
         try:
-            answer = self._conn.exchange1(cmd)
+            answer = self._conn.exchange(cmd)
         except Exception:
             self._logger.error(format_exc())
             answer = DNAErrors.E_UNKNOWN.value
@@ -316,7 +316,7 @@ def getrequest(
         cmd = f"GET/{mode:s}/WI{wordindex:d}"
         comment = ""
         try:
-            answer = self._conn.exchange1(cmd)
+            answer = self._conn.exchange(cmd)
         except Exception:
             self._logger.error(format_exc())
             answer = DNAErrors.E_UNKNOWN.value
@@ -362,7 +362,7 @@ def request(
         """
         comment = ""
         try:
-            answer = self._conn.exchange1(cmd)
+            answer = self._conn.exchange(cmd)
         except Exception:
             self._logger.error(format_exc())
             answer = DNAErrors.E_UNKNOWN.value
diff --git a/src/geocompy/tps1200p/__init__.py b/src/geocompy/tps1200p/__init__.py
@@ -338,7 +338,7 @@ def request(
 
         cmd = f"%R1Q,{rpc}:{','.join(strparams)}"
         try:
-            answer = self._conn.exchange1(cmd)
+            answer = self._conn.exchange(cmd)
         except SerialTimeoutException:
             self._logger.error(format_exc())
             answer = (
diff --git a/src/geocompy/vivatps/__init__.py b/src/geocompy/vivatps/__init__.py
@@ -355,7 +355,7 @@ def request(
 
         cmd = f"%R1Q,{rpc}:{','.join(strparams)}"
         try:
-            answer = self._conn.exchange1(cmd)
+            answer = self._conn.exchange(cmd)
         except SerialTimeoutException:
             self._logger.error(format_exc())
             answer = (
diff --git a/tests/helpers_geocom.py b/tests/helpers_geocom.py
@@ -28,7 +28,7 @@ class DummyGeoComConnection(Connection):
     def send(self, message: str):
         return
 
-    def exchange1(self, cmd: str) -> str:
+    def exchange(self, cmd: str) -> str:
         if not self._CMD.match(cmd):
             return "%R1P,0,0:2"
 
diff --git a/tests/helpers_gsionline.py b/tests/helpers_gsionline.py
@@ -26,10 +26,9 @@ class DummyGsiOnlineConnection(Connection):
     )
 
     def __init__(self, gsi16=False):
-        super().__init__("")
         self._gsi16 = gsi16
 
-    def exchange1(self, cmd: str) -> str:
+    def exchange(self, cmd: str) -> str:
         if self._CONF.match(cmd) and cmd != "CONF/0":
             if cmd == "CONF/137":
                 return f"0137/{self._gsi16:04d}"
