move ping timeout logic into decorator

patch bump

Author: onyx-and-iris

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vban-cmd"
-version = "2.9.4"
+version = "2.9.5"
 description = "Python interface for the VBAN RT Packet Service (Sendtext)"
 authors = [{ name = "Onyx and Iris", email = "code@onyxandiris.online" }]
 license = { text = "MIT" }

uv.lock

@@ -1,6 +1,9 @@
+import socket
 import time
 from typing import Iterator
 
+from .error import VBANCMDConnectionError
+
 
 def ratelimit(func):
     """ratelimit decorator for {VbanCmd}.sendtext, to prevent flooding the network with script requests."""
@@ -18,6 +21,54 @@ def wrapper(*args, **kwargs):
     return wrapper
 
 
+def ping_timeout(func):
+    """ping_timeout decorator for {VbanCmd}._ping, to handle timeout logic and socket management."""
+
+    def wrapper(self, timeout: float = None):
+        if timeout is None:
+            timeout = min(self.timeout, 3.0)
+
+        original_timeout = self.sock.gettimeout()
+        self.sock.settimeout(0.5)
+
+        try:
+            func(self)
+
+            start_time = time.time()
+            response_count = 0
+
+            while time.time() - start_time < timeout:
+                try:
+                    data, addr = self.sock.recvfrom(2048)
+                    response_count += 1
+
+                    self.logger.debug(
+                        f'Received packet #{response_count} from {addr}: {len(data)} bytes'
+                    )
+                    self.logger.debug(
+                        f'Response header: {data[: min(32, len(data))].hex()}'
+                    )
+
+                    result = func(self, data, addr)
+                    if result is True:
+                        return
+
+                except socket.timeout:
+                    continue
+
+            self.logger.debug(
+                f'PING timeout after {timeout}s, received {response_count} non-PONG packets'
+            )
+            raise VBANCMDConnectionError(
+                f'PING timeout: No response from {self.host}:{self.port} after {timeout}s'
+            )
+
+        finally:
+            self.sock.settimeout(original_timeout)
+
+    return wrapper
+
+
 def cache_bool(func, param):
     """Check cache for a bool prop"""