Merge pull request #41 from MrClock8163/feature-timeout-override

Add timeout_override

Author: MrClock8163

src/geocompy/communication.py

@@ -22,7 +22,8 @@
 
 import logging
 from types import TracebackType
-from typing import Literal
+from typing import Literal, Generator
+from contextlib import contextmanager
 
 from serial import (
     Serial,
@@ -412,3 +413,52 @@ def exchange(self, cmd: str) -> str:
         """
         self.send(cmd)
         return self.receive()
+
+    @contextmanager
+    def timeout_override(
+        self,
+        timeout: int | None
+    ) -> Generator[None, None, None]:
+        """
+        Context manager that temporarily overrides connection parameters.
+
+        Parameters
+        ----------
+        timeout : int | None
+            Temporary timeout in seconds. Set to None to wait indefinitely.
+
+        Returns
+        -------
+        Generator
+            Context manager generator object.
+
+        Warning
+        -------
+        An indefinite timeout might leave the connection in a perpetual
+        waiting state, if the instrument became unresponsive in the
+        mean time (e.g. it powered off due to low battery charge).
+
+        Example
+        -------
+
+        >>> from serial import Serial
+        >>> from geocompy.communication import SerialConnection
+        >>>
+        >>> port = Serial("COM1", timeout=5)
+        >>> with SerialConnection(port) as com:
+        ...     # normal operation
+        ...
+        ...     # potentially long operation
+        ...     with com.timeout_override(20):
+        ...         answer = com.exchange("message")
+        ...
+        ...     # continue normal operation
+        ...
+        """
+        saved_timeout = self._port.timeout
+
+        try:
+            self._port.timeout = timeout
+            yield
+        finally:
+            self._port.timeout = saved_timeout